Capital OS

Capital OS is a deterministic, auditable financial truth layer built around a double-entry ledger and schema-validated tool APIs for agent use.

Current Status (2026-02-23)

• Core ledger foundation is implemented: accounts, balanced transaction bundles, idempotency, balance snapshots, obligations, and event logging.
• Capital posture tooling is implemented (compute_capital_posture, compute_consolidated_posture).
• Spend simulation tooling is implemented (simulate_spend) with contract, logging, and latency guardrail coverage.
• Debt analysis tooling is implemented (analyze_debt) with deterministic ranking, explainability payloads, and sensitivity branch support.
• Approval-gated write workflow is implemented (record_transaction_bundle proposal path + approve/reject tools).
• Epic 9 governance expansion is implemented (close_period, lock_period, adjusting-entry enforcement, expanded policy rules, multi-party approvals).
• Epic 6 deterministic read/query surface is implemented (list_transactions, get_transaction_by_external_id, list_obligations, list_proposals, get_proposal, get_config), plus config-governance hooks (propose_config_change, approve_config_change).
• Epic 5 hardening work is implemented: PRD traceability matrix, migration reversibility CI gate, and expanded determinism regression suite.
• Epic 10 security controls are implemented: header-token authentication, config-driven tool authorization, and mandatory correlation IDs.
• Epic 15 CLI operator interface is implemented: trusted local CLI (capital-os) for tool invocation without HTTP server.

Tech Stack

• Python 3.11+
• FastAPI (GET /health, POST /tools/{tool_name})
• SQLite (file-backed, WAL mode)
• Pytest (unit/integration/replay/security/perf)

Repository Layout

src/capital_os/
  api/             # FastAPI transport
  tools/           # Tool handlers and schema boundary
  domain/          # Accounts, ledger, and posture domain logic
  db/              # SQLite connection and transaction helpers
  observability/   # Event log + deterministic hashing
  schemas/         # Pydantic request/response contracts
migrations/        # Numbered schema migrations + rollback scripts
tests/             # Unit/integration/replay/security/perf coverage
docs/              # Project and agent documentation
skills/            # Example SKILL.md files for Codex and Claude

Quickstart

Local Development

1. Install dependencies:

pip install -e ".[dev]"

2. Set database URL (optional, default shown):

export CAPITAL_OS_DB_URL=sqlite:///./data/capital_os.db

3. Run the API:

uvicorn capital_os.main:app --reload

4. Run tests:

pytest

Docker + MCP (Claude Code/Desktop Integration)

1. Build container:

docker build -t capital-os-mcp .

2. Run MCP server (integrates with Claude Desktop):

docker run -i --rm -v capital-os-data:/app/data capital-os-mcp:latest

See docs/docker-mcp-integration.md for full setup and configuration.

CLI (Trusted Local Channel)

The capital-os CLI lets operators invoke tools locally without running the HTTP server. All core invariants (schema validation, deterministic hashing, event logging, transaction boundaries) are preserved through the shared runtime executor.

Install

# Development (editable, recommended)
pip install -e .

# Or with uv
uv pip install -e .

# Operator install via pipx (isolated environment)
pipx install .

Shell Completion

# bash
capital-os --install-completion bash

# zsh
capital-os --install-completion zsh

# fish
capital-os --install-completion fish

To display the completion script without installing:

capital-os --show-completion bash

Quickstart

# Check runtime / DB readiness
capital-os health

# Use a specific database file
capital-os health --db-path /path/to/capital_os.db

# List available tools
capital-os tool list

# Show schema for a tool
capital-os tool schema list_accounts

# Call a tool with inline JSON
capital-os tool call list_accounts --json '{"correlation_id":"local-001"}'

# Call a tool with a JSON file
capital-os tool call create_account --json @payload.json

# Call a tool from stdin
echo '{"correlation_id":"local-002"}' | capital-os tool call list_accounts

# Start the HTTP server
capital-os serve

Security Model

• CLI is a trusted local operator channel — no auth token required.
• All schema validation, event logging, and DB invariants are still enforced.
• CLI executions are distinguishable in the event log via authn_method = "trusted_cli".

Runtime Make Targets

• Bootstrap database + COA seed:

make init

• Start runtime in background (idempotent when already healthy):

make run

• Start runtime with idle auto-shutdown:

CAPITAL_OS_IDLE_SECONDS=300 make serve-idle

• Health check and stop:

make health
make stop

• End-to-end deterministic MVP smoke flow (reset -> migrate -> seed -> serve -> write/read assertions -> stop):

make mvp-smoke

• Runtime state files are written under .run/:
  • .run/capital-os.pid
  • .run/capital-os.url
  • .run/last_request.ts
  • .run/uvicorn.log

COA Bootstrap (MVP)

• config/coa.yaml is the authoritative initial chart-of-accounts seed for bootstrap/reset flows.
• Validate only:

python3 scripts/import_coa.py config/coa.yaml --validate-only

• Seed (idempotent upsert):

python3 scripts/import_coa.py config/coa.yaml

• Dry-run seed:

python3 scripts/import_coa.py config/coa.yaml --dry-run

• Governance boundary:
  • config/coa.yaml is bootstrap/reset only.
  • Post-bootstrap account changes should go through governed API/tool paths.

API Surface

• Health:
  • GET /health
• Tool endpoint:
  • POST /tools/{tool_name}
• Registered tools:
  • record_transaction_bundle
  • record_balance_snapshot
  • create_or_update_obligation
  • compute_capital_posture
  • compute_consolidated_posture
  • simulate_spend
  • analyze_debt
  • approve_proposed_transaction
  • reject_proposed_transaction
  • list_accounts
  • get_account_tree
  • get_account_balances
  • list_transactions
  • get_transaction_by_external_id
  • list_obligations
  • list_proposals
  • get_proposal
  • get_config
  • propose_config_change
  • approve_config_change
  • reconcile_account
  • close_period
  • lock_period

Example Tool Call

curl -sS -X POST http://127.0.0.1:8000/tools/record_transaction_bundle \
  -H "content-type: application/json" \
  -H "x-capital-auth-token: ${CAPITAL_OS_AUTH_TOKEN:-dev-admin-token}" \
  -d '{
    "source_system":"example",
    "external_id":"tx-001",
    "date":"2026-01-01T00:00:00Z",
    "description":"Opening balance",
    "postings":[
      {"account_id":"<asset-account-id>","amount":"100.00","currency":"USD"},
      {"account_id":"<equity-account-id>","amount":"-100.00","currency":"USD"}
    ],
    "correlation_id":"corr-001"
  }'

Core Guarantees

• Balanced transaction bundles are enforced before commit.
• Idempotency key is (source_system, external_id) for transaction recording.
• Monetary values are normalized to 4 decimal places with round-half-even.
• Tool input/output hashing is deterministic.
• Tool invocations are event-logged (success and validation failures).
• Tool invocations require authenticated actor context and capability authorization.
• Append-only protections exist on transaction, posting, and event-log history.

Documentation Index

• docs/README.md
• docs/current-state.md
• docs/tool-reference.md
• docs/data-model.md
• docs/testing-matrix.md
• docs/traceability-matrix.md
• docs/development-workflow.md
• docs/agent-playbooks/README.md
• docs/mvp-bootstrap-agent-testing.md
• docs/backlog-phase1-prd-closure.md

Epic 11 Portability Status

Epic 11 portability features are intentionally deferred in this slice:

• Export ledger with integrity markers
• Controlled import (dry-run and strict mode)
• Admin backup/restore

Planning and Backlog Source of Truth

• Sprint status: _bmad-output/implementation-artifacts/sprint-status.yaml
• Story briefs: _bmad-output/implementation-artifacts/*.md
• Epic planning: _bmad-output/planning-artifacts/epic-*.md
• PRD baseline: initial_prd.md
• Tool auth header (default dev token):

export CAPITAL_OS_AUTH_TOKEN=dev-admin-token