agentorch 0.1.0

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 devtorch
devtorch init
devtorch commit -m "Add payments service"
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

python3 -m venv .venv && source .venv/bin/activate

# Core CLI only
pip install devtorch

# With SDK wrappers (Anthropic, OpenAI, Gemini, Bedrock)
pip install devtorch[wrapper]

# With HTTP proxy + dashboard API (FastAPI)
pip install devtorch[proxy]

# Everything
pip install devtorch[all]

Requirements: Python 3.10+

---

Quick start

cd /path/to/your/project
devtorch init

# Record reasoning commits
devtorch commit -m "Chose idempotent transfer endpoint design"

# Add per-agent branches
devtorch branch app
devtorch branch dba
devtorch branch security-review

# Add sensitivity information
devtorch sensitivity add \
  --source agent-app \
  --concept api_contract \
  --confidence 0.9 \
  --disclosure PUBLIC \
  -m "API shape depends on transaction schema"

# Inspect state
devtorch status
devtorch debug timeline
devtorch debug branch-compare app dba

---

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