agentorch 1.1.1

DevTorch — AI reasoning capture, audit trail, and governance for agent-assisted development

DevTorch

Local-first AI agent governance. DevTorch gives multi-agent systems a shared on-disk audit trail, coordination vector, privacy controls, and LLM integration layer — all without a remote service.

pip install agentorch
devtorch init
devtorch setup          # connects to Claude Code, Cursor, or Antigravity
devtorch debug timeline

---

What it does

Concern	DevTorch feature
Reasoning audit trail	Append-only .GCC/events.log.jsonl with SHA-256 hash chain
Multi-agent coordination	Coordination vector Θ — shared sensitivity map across agents
Privacy compliance	RDP ε-budget tracking; [PRIVATE] span suppression; SIS-TC quarantine
LLM integration	SDK wrappers, HTTP proxy, Claude Code MCP server + hooks
Governance observability	Structured reports, browser dashboard, VS Code extension (Antigravity-compatible)
Alerting	Slack, Jira, PagerDuty outbound webhooks
Metrics	MCS, DHS, ROI — all traceable to citations or explicit design choices

Everything lives in .GCC/ — a local directory in your project. No database, no network service, no telemetry.

---

Install

pip install agentorch

Requirements: Python 3.10+

For optional extras:

pip install agentorch[wrapper]   # SDK wrappers (Anthropic, OpenAI, Gemini, Bedrock, Ollama)
pip install agentorch[proxy]     # HTTP proxy + dashboard API (FastAPI)
pip install agentorch[all]       # everything

The PyPI package is named agentorch. The CLI command and import paths remain devtorch / devtorch_core.

---

Getting Started

DevTorch takes 5 minutes to set up. Pick your AI coding tool below.

Prerequisites: Python 3.10+, pip, and the AI tool you plan to use.

---

Claude Code

Claude Code is the highest-fidelity integration — hooks fire on every file write, MCP tools give Claude native governance commands, and CLAUDE.md carries persistent instructions across sessions.

Step 1 — Install DevTorch

pip install agentorch

Step 2 — Go to your project and run setup

cd /path/to/your/project
devtorch setup

This single command:

• Initialises .GCC/ (the local governance store)
• Writes .claude/hooks.json so hooks fire on every Write, Edit, Bash, and Stop event
• Adds the DevTorch MCP server to .claude/settings.json
• Writes governance instructions into CLAUDE.md

Step 3 — Verify

devtorch doctor

Expected output: all checks green. If any check fails, the doctor output tells you exactly what to fix.

Step 4 — Start using Claude Code

Open Claude Code in your project. On the first task Claude will call devtorch_context to load prior reasoning, and devtorch_commit before any file edit. The .GCC/ store captures everything automatically.

What you get: Full RACP integration — reasoning commits, sensitivity events, coordination vector Θ, divergence detection, HITL conflict resolution.

---

Cursor

Cursor is a VS Code fork with native MCP support. DevTorch integrates via MCP tools and the VS Code sidebar extension.

Step 1 — Install DevTorch

pip install agentorch

Step 2 — Run setup

cd /path/to/your/project
devtorch setup --target cursor

This creates .cursor/mcp.json wiring the DevTorch MCP server into Cursor, initialises .GCC/, and writes CLAUDE.md with governance instructions.

Step 3 — Add Cursor rules

Create .cursor/rules/devtorch.mdc:

---
alwaysApply: true
---
Before any file edit, call devtorch_commit with your reasoning and the concepts you are touching.
Call devtorch_context at the start of each task to load prior decisions.
Call devtorch_sensitivity_add when touching auth, payments, schema, secrets, or PII.

Step 4 — Install the VS Code extension (optional but recommended)

In Cursor: Cmd+Shift+P → "Extensions: Install from VSIX" → select extensions/vscode/devtorch-0.1.0.vsix from the DevTorch source directory. This adds a live sidebar panel showing .GCC/ state, Θ hot zones, and the event feed.

Step 5 — Verify

devtorch doctor

What you get: MCP tools, VS Code sidebar, optional HTTP proxy for passive capture of all LLM calls (devtorch proxy start).

---

Google Antigravity

Google Antigravity is a VS Code fork with a multi-agent orchestration layer. It reads AGENTS.md for persistent AI instructions and supports MCP servers.

Step 1 — Install DevTorch

pip install agentorch

Step 2 — Run setup

cd /path/to/your/project
devtorch setup --target antigravity

This initialises .GCC/, writes the DevTorch MCP server config for Antigravity, and writes governance instructions into AGENTS.md.

Step 3 — Install the VS Code extension

In Antigravity: Cmd+Shift+P → "Extensions: Install from VSIX" → select extensions/vscode/devtorch-0.1.0.vsix.

Step 4 — Verify

devtorch doctor

What you get: Full RACP integration. The multi-agent nature of Antigravity makes Θ accumulation especially valuable — multiple agents share the same reasoning state through devtorch_context.

---

VS Code (with GitHub Copilot)

VS Code + Copilot has partial integration only. Copilot's API is closed — DevTorch cannot intercept completions or inject RACP context. What works: the sidebar panel showing .GCC/ state, and git-commit-level capture via the git hook.

Step 1 — Install DevTorch

pip install agentorch
cd /path/to/your/project
devtorch init
devtorch hooks install

Step 2 — Install the VS Code extension

Cmd+Shift+P → "Extensions: Install from VSIX" → select extensions/vscode/devtorch-0.1.0.vsix.

The sidebar shows your branch, last commit, Θ hot zones, and the live event feed from .GCC/.

Step 3 — Record reasoning manually

Since Copilot's internal reasoning cannot be captured automatically, record your own reasoning commits:

devtorch commit -m "Chose JWT over sessions — stateless service, no session store needed"
devtorch sensitivity add --source you --concept auth --confidence 0.9 --disclosure PROTECTED -m "Token expiry logic is security-critical"

What you get: Sidebar panel (read-only), git-commit-level event capture, manual reasoning commits. Full capture requires switching to Claude Code, Cursor, Kiro, or Antigravity.

---

AWS Kiro

Kiro is Amazon's AI IDE. It uses steering documents and hooks — analogous to CLAUDE.md and hooks.json. Full DevTorch integration is available via manual configuration.

Step 1 — Install DevTorch

pip install agentorch
cd /path/to/your/project
devtorch init

Step 2 — Add the MCP server

Create .kiro/settings/mcp.json:

{
  "mcpServers": {
    "devtorch": {
      "command": "/absolute/path/to/.venv/bin/devtorch",
      "args": ["mcp-server"],
      "env": {}
    }
  }
}

Replace /absolute/path/to/.venv/bin/devtorch with the output of which devtorch.

Step 3 — Add steering document

Create .kiro/steering/devtorch.md with inclusion: always:

---
inclusion: always
---

# DevTorch Governance

Before any file edit, call `devtorch_commit` with your reasoning and the concepts you are touching.
Call `devtorch_context` at the start of each task to load prior decisions.
Call `devtorch_sensitivity_add` when touching auth, payments, schema, secrets, or PII.

Step 4 — Add agent hook

Create .kiro/hooks/devtorch-capture.md:

---
name: devtorch-capture
trigger: after-file-write
---
Run: devtorch hooks run post-tool-use

Step 5 — Verify

devtorch doctor

What you get: Full RACP integration equivalent to Claude Code — MCP tools, steering-document governance, agent action hooks.

---

AWS Bedrock (Python SDK)

DevTorch integrates at the boto3 call level with a one-line change.

Step 1 — Install

pip install agentorch[wrapper] boto3
cd /path/to/your/project
devtorch init

Step 2 — Wrap your Bedrock client

# Before
import boto3
client = boto3.client("bedrock-runtime", region_name="us-east-1")

# After — one import change, same API
from devtorch_core.wrapper.bedrock import DevTorchBedrock
client = DevTorchBedrock(region_name="us-east-1")

All invoke_model() and converse() calls are identical. DevTorch injects the RACP system prefix and captures responses automatically.

Step 3 — Verify

devtorch doctor

---

Azure AI Foundry (Python SDK)

Step 1 — Install

pip install agentorch[wrapper] openai
cd /path/to/your/project
devtorch init

Step 2 — Wrap your Azure OpenAI client

# Before
from openai import AzureOpenAI

# After — one import change, all kwargs pass through unchanged
from devtorch_core.wrapper.openai import DevTorchOpenAI as AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://my-resource.openai.azure.com/",
    api_version="2024-02-01",
    api_key=os.environ["AZURE_OPENAI_KEY"],
)
# All chat.completions.create() calls are identical

Step 3 — Verify

devtorch doctor

---

OpenAI Codex CLI

Step 1 — Install

pip install agentorch
cd /path/to/your/project
devtorch init

Step 2 — Start the proxy

devtorch proxy start   # runs on localhost:8765

Step 3 — Point Codex at the proxy

export OPENAI_BASE_URL=http://localhost:8765/v1
codex "Add error handling to the payment service"

All Codex calls are intercepted by the proxy, which injects the RACP prefix and captures responses into .GCC/.

---

Ollama (local models)

Step 1 — Install Ollama and pull a model

# Install Ollama from https://ollama.com
ollama pull llama3.2

Step 2 — Install DevTorch

pip install agentorch[wrapper]
cd /path/to/your/project
devtorch init

Step 3 — Wrap your Ollama client

from devtorch_core.wrapper.ollama import DevTorchOllama

client = DevTorchOllama(model="llama3.2")   # any model in `ollama list`
response = client.chat(messages=[{"role": "user", "content": "Explain this function"}])

Step 4 — Verify

devtorch doctor

No API key required. Fully local — RACP context and captures stay on-device.

---

Platform comparison

Platform	Setup command	MCP tools	Auto-capture	Sidebar	Notes
Claude Code	devtorch setup	✅	✅ hooks	✅	Highest fidelity
Cursor	devtorch setup --target cursor	✅	✅ proxy	✅	Near-full
Google Antigravity	devtorch setup --target antigravity	✅	✅	✅	Full
AWS Kiro	Manual (5 steps)	✅	✅ hooks	✅	Full — not yet automated
VS Code + Copilot	devtorch init + extension	❌	❌ git only	✅	Partial — Copilot API closed
AWS Bedrock	SDK wrapper	—	✅ SDK	—	Python SDK only
Azure AI Foundry	SDK wrapper or proxy	—	✅ SDK	—	Python SDK only
OpenAI Codex CLI	HTTP proxy	—	✅ proxy	—
Ollama	SDK wrapper	—	✅ SDK	—	Fully local

---

LLM integration

Option 1 — SDK wrapper (you own the code)

# One-line change — same API, governance captured automatically
from devtorch_core.wrapper.anthropic import DevTorchAnthropic
client = DevTorchAnthropic()   # replaces anthropic.Anthropic()

# OpenAI
from devtorch_core.wrapper.openai import DevTorchOpenAI
client = DevTorchOpenAI()

# Local models via Ollama (no API key required)
from devtorch_core.wrapper.ollama import DevTorchOllama
client = DevTorchOllama(model="llama3.2")   # any model in `ollama list`

# Google Gemini
from devtorch_core.wrapper.gemini import DevTorchGemini
client = DevTorchGemini(model_name="gemini-1.5-pro")

# AWS Bedrock
from devtorch_core.wrapper.bedrock import DevTorchBedrock
client = DevTorchBedrock(region_name="us-east-1")

See OLLAMA_SETUP.md for the full Ollama guide.

Option 2 — HTTP proxy (Cursor, JetBrains, closed-source IDEs)

devtorch proxy install   # installs as macOS LaunchAgent or Linux systemd service
devtorch proxy start     # runs on localhost:8765

Configure your IDE to use http://localhost:8765/anthropic (or /openai, /gemini). The proxy injects RACP context and captures responses with zero latency penalty.

Option 3 — MCP server + hooks (Claude Code, Cursor, Kiro, Antigravity)

devtorch setup   # one command: init + hooks + MCP config + CLAUDE.md + AGENTS.md

Claude Code / Cursor / Kiro / Antigravity then call devtorch_commit, devtorch_sensitivity_add, devtorch_context, and devtorch_theta_read as native MCP tools. See IDE_SETUP.md for per-IDE instructions.

Option 4 — OpenAI Codex CLI proxy

# Start the Codex-specific proxy on localhost:8766
python -m devtorch_core.codex start

# Point Codex CLI at it
export OPENAI_BASE_URL=http://localhost:8766/v1
codex "Add error handling to the payment service"

See CODEX_SETUP.md for the full guide.

Option 5 — Org gateway (enterprise, multi-developer)

cd deploy/
cp .env.example .env   # set ANTHROPIC_API_KEY and/or OPENAI_API_KEY
docker compose up      # gateway on :8080, dashboard on :3000

Developers point their IDE proxy URL to the gateway instead of api.openai.com. The gateway handles central API key management, SSO attribution, governance policy enforcement, and metrics aggregation. See deploy/README.md for Helm and Docker Compose instructions.

---

Architecture

devtorch_core/           Pure library — all business logic
  gcc.py                 GCCRepository: .GCC/ layout, event log, commits, branches
  sensitivity.py         Sensitivity events + SensitivityStore
  theta.py               Coordination vector Θ + AggPhi
  capability.py          OmegaCapability (A1), Lipschitz bound, PST runner
  invariants.py          I1 (commit-backed), I3 (semantic grounding)
  variance.py            f_max formula, rolling monitor, VARIANCE_ALERT
  rep.py                 REP ledger — append-only local transport
  sis.py                 SIS-TC corpus evaluation + quarantine
  rdp.py                 RDP ε-budget tracking
  disclosure.py          [PRIVATE] span suppression
  prompt_artifact.py     RACP system prompt artifact store
  deltaf.py              Δf estimation
  parser/                XML block extractor, thinking tokens, inference
  wrapper/               SDK drop-in wrappers (Anthropic, OpenAI, Gemini, Bedrock)
  proxy/                 HTTP reverse proxy (localhost:8765)
  mcp/                   MCP/JSON-RPC server
  hooks/                 Claude Code hooks + git commit-msg hook
  metrics/               MCS, DHS, ROI, calibration, citation registry
  observability/         Structured reports + enterprise metrics webhook
  alerts/                Slack, Jira, PagerDuty outbound alerting
  rep_network/           Multi-node REP ledger sync
  github/                GitHub App webhook + PR comment builder
  dashboard_api.py       REST API for browser dashboard

devtorch_cli/
  main.py                Thin argparse wrapper over devtorch_core

extensions/vscode/       VS Code extension (read-only sidebar; installs in Antigravity via .vsix)
dashboard/               React browser dashboard (Developer/Lead/CISO views)
tests/                   637 tests across all sprints (S0–S18)
examples/                end-to-end scenario examples

---

On-disk layout (.GCC/)

.GCC/
  VERSION                    # format version
  events.log.jsonl           # append-only audit stream (hash chain)
  main.md / log.md           # reasoning roadmap + chronological log
  refs/HEAD                  # current branch
  refs/branches/<name>       # branch tip commit ID
  commits/<id>.json          # commit objects
  sensitivities/events.jsonl # raw sensitivity events
  theta.json                 # coordination vector Θ
  capabilities/omega.json    # A1 capability state
  variance/                  # calibration_report.json, live_state.json
  rep/rep_ledger.jsonl        # REP transport ledger
  rep/peers.json             # peer list for multi-node sync
  sis/                       # SIS-TC corpus, reports, quarantine events
  rdp/rdp_state.json         # RDP ε-budget
  concepts/<name>.json       # I3 concept definitions
  prompts/                   # RACP system prompt artifact
  deltaf/                    # Δf report
  calibration.json           # team-specific metric calibration
  context_bundles/           # MECW-bounded context snapshots
  NODE_STATE                 # node state machine

---

Key safety properties

Property	Mechanism
Commit-backed decisions (I1)	Merge/unlock blocked unless branch tips exist in commits/ and events log
Semantic grounding (I3)	Operations using concepts_used require matching definitions in concepts/
Capability gate (A1)	Textual mode requires valid OmegaCapability + passing PST
Variance control (A2)	f_max=0 forces deterministic mode; A1 gate blocks textual_mode
Privacy budget (RDP)	epsilon exhaustion flips read_only=true in rdp_state.json
Proxy trust boundary	Proxy binds to 127.0.0.1 only; API keys pass through, never stored

---

Run the tests

python3 -m venv .venv && source .venv/bin/activate
pip install -e .[dev,proxy]
pytest tests/         # 637 tests

---

Configuration reference

Env var	Purpose
DEVTORCH_DISABLE=1	Disable all injection and capture (wrapper/proxy become transparent)
DEVTORCH_SLACK_WEBHOOK_URL	Slack alert delivery
DEVTORCH_JIRA_URL / _PROJECT_KEY / _API_TOKEN / _EMAIL	Jira issue creation
DEVTORCH_PAGERDUTY_ROUTING_KEY	PagerDuty event trigger
DEVTORCH_ALERT_MIN_SEVERITY	Minimum severity to alert on (info/warning/critical)
DEVTORCH_METRICS_WEBHOOK_URL	Enterprise metrics webhook endpoint
DEVTORCH_ORG_ID	Org identifier in metrics payloads
DEVTORCH_METRICS_API_KEY	Auth for metrics webhook
DEVTORCH_GITHUB_WEBHOOK_SECRET	HMAC secret for GitHub App webhook

---

Documentation

File	Contents
DOCS.md	Architecture deep-dive, Sprint 4–6 feature reference, conformance matrix
OBSERVABILITY.md	Observability pillars, daily-recall pattern, shell audit script template
CONTRIBUTING.md	Dev environment, test commands, sprint structure, PR checklist
THREAT_MODEL.md	Trust model, hash chain integrity, proxy trust boundary, known limitations
DESIGN_THOUGHTS.md	Design decisions Q1–Q14 with full citation validation
IDE_SETUP.md	VS Code, Cursor, Kiro, and Antigravity setup instructions
ANTIGRAVITY_SETUP.md	Google Antigravity step-by-step onboarding
CLAUDE_CODE_QUICKSTART.md	Claude Code step-by-step onboarding
OLLAMA_SETUP.md	Local model setup with Ollama (Llama, Mistral, Gemma, Phi, Qwen)
CODEX_SETUP.md	OpenAI Codex CLI proxy setup
AGENTS.md	Persistent AI instructions for Antigravity/Kiro
deploy/README.md	Enterprise org gateway — Docker Compose and Helm deployment
devtorch_core/metrics/README.md	MCS/DHS/ROI formulas and calibration guide
devtorch_core/proxy/README.md	HTTP proxy deployment options
devtorch_core/wrapper/README.md	SDK wrapper quick-start for all providers
dashboard/README.md	Browser dashboard setup and API reference

---

Metrics credibility

DevTorch is explicit about what every number is based on:

• 15 min context switch — Parnin & Rugaber (2011), Software Quality Journal. DOI: 10.1007/s11219-010-9104-9. Measured for programming tasks only.
• Auditor rate — BLS SOC 13-2011 (2023): $39–40/hr employed staff. External rates ($75–400/hr) not used as defaults.
• MCS/DHS weights — Design choices. No external benchmark. Calibrate with your team's data.
• Developer hourly rate — No default. You must set it: devtorch calibrate --set developer_hourly_rate=<value>

See devtorch_core/metrics/credibility.py for the full citation registry.

---

License

Apache 2.0