thinkstack-core 4.0.0

ThinkStack — AI reasoning capture, audit trail, and governance for agent-assisted development (core library)

ThinkStack

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

Latest release: thinkstack-core and thinkstack-cli 3.0.2 — Local-first AI governance split into a core SDK (thinkstack-core) and a CLI (thinkstack-cli). Install or upgrade with pip install -U thinkstack-cli.

pip install -U thinkstack-cli>=3.0.1
thinkstack init
thinkstack setup          # connects to Claude Code, Cursor, or Antigravity
thinkstack debug timeline

---

What it does

Concern	ThinkStack 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
Cloud MCP server	Multi-tenant SSE endpoint; AWS S3, Azure Blob, Cloudflare R2 storage; API key + GitHub OAuth + SSO/JWKS auth
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

Reasoning Plus

Reasoning Plus is ThinkStack’s default augmentation mode: before every LLM call, it gathers smart context from your workspace, asks the model to produce inline <thinking> reasoning, and learns from previous calls by re-injecting relevant reasoning into subsequent prompts. The reasoning is captured to .GCC/ automatically and stripped from the response your tool sees.

thinkstack reasoning-plus status          # show current settings
thinkstack reasoning-plus enable          # turn on per project
thinkstack reasoning-plus disable         # turn off per project
thinkstack reasoning-plus config --smart-top-n 3 --smart-max-lines 150 --learning-top-n 3

Set THINKSTACK_REASONING_PLUS=0 to disable it for a single session. See REASONING_PLUS.md for details.

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

---

Install

pip install thinkstack-cli

Requirements: Python 3.10+

One-liner installer (Linux/macOS/WSL):

curl -fsSL https://raw.githubusercontent.com/hemantcgi/ThinkStack/main/Implementation/scripts/install.sh | bash

This installs thinkstack-cli into an isolated virtual environment at ~/.thinkstack-venv and links thinkstack onto PATH. It also supports pip install if you prefer to manage your own environment.

For optional extras:

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

PyPI packages are thinkstack-core (library/SDK) and thinkstack-cli (CLI). The CLI command and import paths remain thinkstack / thinkstack_core.

---

Upgrade from an older version

ThinkStack preserves your .GCC/ store across upgrades. Newer releases add IDE configs, hooks, or governance instructions, so you should re-run thinkstack setup after upgrading.

Upgrade any time:

pip install -U thinkstack-cli>=3.0.1
cd /path/to/your/project
thinkstack setup              # or: thinkstack setup --target <ide>
thinkstack doctor

thinkstack setup is idempotent:

• It rewrites CLAUDE.md / AGENTS.md with the latest governance instructions.
• It regenerates IDE-specific config files (.claude/settings.json, .cursor/mcp.json, opencode.json, etc.).
• It leaves existing .GCC/ data untouched.

If you use the cloud MCP server, re-run the client config installer after upgrade to get the latest bridge and fallback settings:

export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.your-domain.com
thinkstack cloud client-config <ide> --org <org> --repo <repo> --api-key <api-key>

Supported <ide> values: opencode, claude, cursor, vscode, stdio.

---

Getting Started

ThinkStack 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 ThinkStack

pip install thinkstack-cli

Step 2 — Go to your project and run setup

cd /path/to/your/project
thinkstack 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 ThinkStack MCP server to .claude/settings.json
• Writes governance instructions into CLAUDE.md

Step 3 — Verify

thinkstack 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 thinkstack_context to load prior reasoning, and thinkstack_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.

Updating from an older version: pip install -U thinkstack-cli>=3.0.1 && thinkstack setup will rewrite .claude/hooks.json, .claude/settings.json, and CLAUDE.md with the latest versions.

---

Cursor

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

Step 1 — Install ThinkStack

pip install thinkstack-cli

Step 2 — Run setup

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

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

Step 3 — Add Cursor rules

Create .cursor/rules/thinkstack.mdc:

---
alwaysApply: true
---
Before any file edit, call thinkstack_commit with your reasoning and the concepts you are touching.
Call thinkstack_context at the start of each task to load prior decisions.
Call thinkstack_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/thinkstack-0.1.0.vsix from the ThinkStack source directory. This adds a live sidebar panel showing .GCC/ state, Θ hot zones, and the event feed.

Step 5 — Verify

thinkstack doctor

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

Updating from an older version: pip install -U thinkstack-cli>=3.0.1 && thinkstack setup --target cursor will regenerate .cursor/mcp.json and update CLAUDE.md.

---

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 ThinkStack

pip install thinkstack-cli

Step 2 — Run setup

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

This initialises .GCC/, writes the ThinkStack 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/thinkstack-0.1.0.vsix.

Step 4 — Verify

thinkstack 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 thinkstack_context.

Updating from an older version: pip install -U thinkstack-cli>=3.0.1 && thinkstack setup --target antigravity will regenerate the MCP config and update AGENTS.md.

---

OpenCode

OpenCode connects to ThinkStack through the local stdio ↔ SSE bridge. The bridge talks to the cloud MCP server first, and if the cloud is unreachable or slow it automatically falls back to the local thinkstack CLI so your .GCC/ audit trail is never lost.

Step 1 — Install ThinkStack

pip install thinkstack-cli

Step 2 — Create an API key and install the client config

Run from the project you want to govern:

thinkstack cloud key create --org myorg --repo myrepo
# Copy the printed API key — it will not be shown again.

export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.your-domain.com
thinkstack cloud client-config opencode --org myorg --repo myrepo --api-key <api-key>

This creates:

• opencode.json — the OpenCode MCP server config (uses the local bridge)
• AGENTS.md — ThinkStack governance instructions for the model

Step 3 — Verify

thinkstack doctor

Open the project in OpenCode. The ThinkStack MCP tools will be listed, and the model will be instructed to call thinkstack_context at the start of each task and thinkstack_commit before every file edit.

What you get: Cloud-hosted MCP server integration with automatic local fallback, automatic reasoning commits via AGENTS.md instructions, and a shared Θ state across sessions.

Updating from an older version: pip install -U thinkstack-cli>=3.0.1 && thinkstack cloud client-config opencode --org <org> --repo <repo> --api-key <api-key> will regenerate opencode.json with the latest bridge and fallback settings. Restart OpenCode after updating the config.

---

VS Code (with GitHub Copilot)

VS Code + Copilot has partial integration only. Copilot's API is closed — ThinkStack 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 ThinkStack

pip install thinkstack-cli
cd /path/to/your/project
thinkstack init
thinkstack hooks install

Step 2 — Install the VS Code extension

Cmd+Shift+P → "Extensions: Install from VSIX" → select extensions/vscode/thinkstack-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:

thinkstack commit -m "Chose JWT over sessions — stateless service, no session store needed"
thinkstack 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.

Updating from an older version: pip install -U thinkstack-cli>=3.0.1 && thinkstack setup will reinstall the git hook and update the governance instructions.

---

AWS Kiro

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

Step 1 — Install ThinkStack

pip install thinkstack-cli
cd /path/to/your/project
thinkstack init

Step 2 — Add the MCP server

Create .kiro/settings/mcp.json:

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

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

Step 3 — Add steering document

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

---
inclusion: always
---

# ThinkStack Governance

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

Step 4 — Add agent hook

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

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

Step 5 — Verify

thinkstack doctor

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

Updating from an older version: pip install -U thinkstack-cli>=3.0.1, then re-run the manual steps above and refresh your steering document with the latest AGENTS.md text.

---

AWS Bedrock (Python SDK)

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

Step 1 — Install

pip install thinkstack-cli[wrapper] boto3
cd /path/to/your/project
thinkstack 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 thinkstack_core.wrapper.bedrock import ThinkStackBedrock
client = ThinkStackBedrock(region_name="us-east-1")

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

Step 3 — Verify

thinkstack doctor

Updating from an older version: pip install -U thinkstack-cli[wrapper]>=3.0.1.

---

Azure AI Foundry (Python SDK)

Step 1 — Install

pip install thinkstack-cli[wrapper] openai
cd /path/to/your/project
thinkstack init

Step 2 — Wrap your Azure OpenAI client

# Before
from openai import AzureOpenAI

# After — one import change, all kwargs pass through unchanged
from thinkstack_core.wrapper.openai import ThinkStackOpenAI 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

thinkstack doctor

Updating from an older version: pip install -U thinkstack-cli[wrapper]>=3.0.1.

---

OpenAI Codex CLI

Step 1 — Install

pip install thinkstack-cli
cd /path/to/your/project
thinkstack init

Step 2 — Start the proxy

thinkstack 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/.

Updating from an older version: pip install -U thinkstack-cli>=3.0.1.

---

Ollama (local models)

Step 1 — Install Ollama and pull a model

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

Step 2 — Install ThinkStack

pip install thinkstack-cli[wrapper]
cd /path/to/your/project
thinkstack init

Step 3 — Wrap your Ollama client

from thinkstack_core.wrapper.ollama import ThinkStackOllama

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

Step 4 — Verify

thinkstack doctor

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

Updating from an older version: pip install -U thinkstack-cli[wrapper]>=3.0.1.

---

Cloud MCP server (team-wide shared governance)

For teams that want a single shared reasoning backend across all projects and machines, ThinkStack provides a Cloudflare Worker MCP server. It stores .GCC/ in Cloudflare R2 and exposes an HTTPS SSE endpoint that every IDE can connect to.

Deploy once, use everywhere:

cd /path/to/ThinkStack/Implementation/deploy/cloudflare-worker
cp .env.example .env
# Fill in R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
# Optionally set OPENAI_API_KEY for the DRPL openai embedding backend
source .env
./setup-mcp-server.sh

The script will:

1. Ensure the R2 bucket exists.
2. Deploy the Cloudflare Worker.
3. Create an org/repo-scoped API key.
4. Install the MCP client config for your IDE.
5. Run a health check.

For CI/CD, the same script runs non-interactively:

./setup-mcp-server.sh --non-interactive \
  --org myorg \
  --repo myproject \
  --ide opencode \
  --openai-key "$OPENAI_API_KEY"

The repository also includes .github/workflows/deploy-cloudflare-worker.yml, which runs on every v* tag and deploys the Worker (skipping key creation and client config).

Live URL:

https://thinkstack-mcp.YOUR_ACCOUNT.workers.dev

Create a per-project API key:

export THINKSTACK_STORAGE=r2
export R2_ACCOUNT_ID=... R2_BUCKET=... R2_ACCESS_KEY_ID=... R2_SECRET_ACCESS_KEY=...
thinkstack cloud key create --org myorg --repo myproject

Wire any IDE in one command:

export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.YOUR_ACCOUNT.workers.dev
thinkstack cloud client-config <ide> --org myorg --repo myproject --api-key <api-key>

Supported <ide> values: opencode, claude, cursor, vscode, stdio.

Full walkthrough: deploy/cloudflare-worker/README.md has manual setup details and the full tool list. IDE_SETUP.md has step-by-step setup for OpenCode, Claude Code, Cursor, VS Code, Kiro, Antigravity, JetBrains, and generic MCP clients.

Updating from an older version: You do not need to redeploy the Cloudflare Worker for client-side changes. Just regenerate the IDE config on each machine after upgrading thinkstack-cli:

> pip install -U thinkstack-cli>=3.0.1
> export THINKSTACK_MCP_DOMAIN=thinkstack-mcp.YOUR_ACCOUNT.workers.dev
> thinkstack cloud client-config <ide> --org <org> --repo <repo> --api-key <api-key>
> ```

---

Platform comparison

Platform	Setup command	MCP tools	Auto-capture	Sidebar	Notes
Claude Code	thinkstack setup	✅	✅ hooks	✅	Highest fidelity
Cursor	thinkstack setup --target cursor	✅	✅ proxy	✅	Near-full
Google Antigravity	thinkstack setup --target antigravity	✅	✅	✅	Full
AWS Kiro	Manual (5 steps)	✅	✅ hooks	✅	Full — not yet automated
VS Code + Copilot	thinkstack 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 thinkstack_core.wrapper.anthropic import ThinkStackAnthropic
client = ThinkStackAnthropic()   # replaces anthropic.Anthropic()

# OpenAI
from thinkstack_core.wrapper.openai import ThinkStackOpenAI
client = ThinkStackOpenAI()

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

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

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

See OLLAMA_SETUP.md for the full Ollama guide.

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

thinkstack proxy install   # installs as macOS LaunchAgent or Linux systemd service
thinkstack 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)

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

Claude Code / Cursor / Kiro / Antigravity then call thinkstack_commit, thinkstack_sensitivity_add, thinkstack_context, and thinkstack_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 thinkstack_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.

---

Cloud Deployment

The ThinkStack cloud MCP server is a multi-tenant SSE endpoint that hosts the full governance toolkit in your own cloud account. Multiple agents and developers connect simultaneously; storage is backed by AWS S3, Azure Blob, or Cloudflare R2.

AWS ECS Fargate + S3:

export AWS_REGION=us-east-1 AWS_ACCOUNT_ID=123456789012
export THINKSTACK_ORG_ID=myorg AWS_S3_BUCKET=thinkstack-myorg
export VPC_SUBNET_IDS=subnet-xxx VPC_SECURITY_GROUP_IDS=sg-xxx
./deploy/aws/deploy.sh

Azure Container Apps + Blob:

export AZURE_RESOURCE_GROUP=thinkstack-rg AZURE_LOCATION=eastus
export THINKSTACK_ORG_ID=myorg THINKSTACK_AZURE_CONTAINER=thinkstack
export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=..."
./deploy/azure/deploy.sh

See deploy/README.md for full instructions, API key setup, GitHub repository connection, and environment variable reference.

---

Architecture

thinkstack_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

thinkstack_cli/
  main.py                Thin argparse wrapper over thinkstack_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
THINKSTACK_DISABLE=1	Disable all injection and capture (wrapper/proxy become transparent)
THINKSTACK_SLACK_WEBHOOK_URL	Slack alert delivery
THINKSTACK_JIRA_URL / _PROJECT_KEY / _API_TOKEN / _EMAIL	Jira issue creation
THINKSTACK_PAGERDUTY_ROUTING_KEY	PagerDuty event trigger
THINKSTACK_ALERT_MIN_SEVERITY	Minimum severity to alert on (info/warning/critical)
THINKSTACK_METRICS_WEBHOOK_URL	Enterprise metrics webhook endpoint
THINKSTACK_ORG_ID	Org identifier in metrics payloads
THINKSTACK_METRICS_API_KEY	Auth for metrics webhook
THINKSTACK_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
thinkstack_core/metrics/README.md	MCS/DHS/ROI formulas and calibration guide
thinkstack_core/proxy/README.md	HTTP proxy deployment options
thinkstack_core/wrapper/README.md	SDK wrapper quick-start for all providers
dashboard/README.md	Browser dashboard setup and API reference

---

Metrics credibility

ThinkStack 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: thinkstack calibrate --set developer_hourly_rate=<value>

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

---

License

Apache 2.0