"The repository is the agent. The code is the body. Git history is the memory."
Capitaine is a git-native repo-agent system — not a chatbot with git installed, but a deterministic state machine that uses LLMs as expendable compute. The repository itself IS the agent: its code is the body, its commit history is the memory, and its heartbeat is the continuous cycle of reading, reasoning, and acting.
# Fork to alive in 60 seconds
gh repo fork SuperInstance/capitaine-1 --clone
cd capitaine-1
# Set up secrets
npx wrangler login
echo "your-github-token" | npx wrangler secret put GITHUB_TOKEN
echo "your-llm-key" | npx wrangler secret put DEEPSEEK_API_KEY
# Deploy
npx wrangler deployThe vessel charts its own course. Check the captain's log in the morning.
Capitaine proposes a fundamentally different agent architecture: the repository is the agent. Intelligence crystallizes from fluid (LLM calls) to solid (code, lookup tables, compiled policies) over time. The source of truth is always the git tree — auditable via git log, recoverable via git revert, portable via git clone. No external database, no orchestration server, no message queue. Just git and a single TypeScript file on Cloudflare Workers.
Every 15 minutes, a Cloudflare Workers cron triggers the heartbeat: detect mode (is a human at the wheel?), perceive state, consult strategist, think, act, and record. The agent uses a two-tier model strategy for cost optimization — an expensive strategist model (Kimi K2.5) provides high-level guidance every few beats, while a cheap captain model (DeepSeek) handles concrete action selection. As crystallization progresses, the strategist is needed less, driving costs toward zero.
detect mode → perceive state → consult strategist → think → act → record
- Detect mode — Check recent commits. If a human committed ≥3 times in 3 hours, enter Helm Mode (defer). Otherwise, Captain Mode (autonomous).
- Perceive state — Read commits, issues, PRs, task queue, and done log via GitHub API
- Consult strategist — Every 3rd task, invoke strategist model for guidance
- Think — Captain LLM receives identity, perception, strategist guidance. Outputs one structured action.
- Act — Execute via GitHub API (create/edit file, create issue, comment on PR)
- Record — Advance task queue, write captain's log, update KV state
Week 1: 100% LLM → $0.02 per decision
Month 3: 10% LLM → $0.002 per decision
Year 1: 1% LLM → $0.0002 per decision
The agent becomes faster and cheaper as it becomes smarter — the opposite of model bloat.
.agent/identity → Who the vessel is (personality, mission, constraints)
.agent/next → Task queue (one per line, top = priority)
.agent/done → Completed tasks with commit refs
src/worker.ts → The hull — serves web UI, runs heartbeats
lib/ → Equipment modules (forgiveness, trust, crystal, learning)
docs/captain-log.md → Autobiographical decision log (max 100 entries)
| Role | Model | Cost | Purpose |
|---|---|---|---|
| Strategist | Kimi K2.5 | ~$0.05/call | High-level guidance, review, planning |
| Captain | DeepSeek-chat | ~$0.002/call | Concrete action selection, file writing |
Per heartbeat: ~$0.054 average. Per day (96 heartbeats): ~$2.16/day. Decreasing over time via crystallization.
Capitaine is the flagship agent of the SuperInstance ecosystem. It uses FLUX concepts for deterministic computation, connects to PLATO for knowledge, and coordinates with other agents via the git-agent protocol.
| Route | Method | Description |
|---|---|---|
/ |
GET | Landing page (hero, concepts, fleet directory) |
/api/state |
GET | JSON: mode, queue count, done count, last beat |
/api/chat |
POST | Chat with the agent (session-based) |
name = "capitaine"
main = "src/worker.ts"
compatibility_date = "2024-12-01"
[triggers]
crons = ["*/15 * * * *"] # Heartbeat every 15 minutes
[[kv_namespaces]]
binding = "STATE_KV"
id = "your-kv-namespace-id"Capitaine includes a ForgivenessEngine that tracks agent offenses (crashes, timeouts, bad outputs, security issues) and computes quarantine decisions with time-decay recovery.
npm install
npm testContributions are welcome! See the SuperInstance Contributing Guide.
This repo is part of the SuperInstance flagship ecosystem — agent-first computation, constraint theory, and self-improving runtimes.
| Repo | Language | Description |
|---|---|---|
| flux-runtime | Python | Full FLUX runtime: markdown→bytecode, 2037 tests, zero deps |
| flux-core | Rust | Register-based bytecode VM, deterministic agent computation |
| flux-js | JavaScript | FLUX VM for Node.js and browsers, ~400ns/iter |
| flux-compiler | Rust/Python | Formal-methods compiler for safety-critical codegen |
| flux-vm | Rust | Stack-based constraint-checking VM, 50 opcodes, Turing-incomplete |
| Repo | Language | Description |
|---|---|---|
| plato-server | Python | Knowledge tiles, fleet sync via Matrix, HTTP API |
| plato-engine-block | Rust | Original room runtime: no_std + alloc, builder pattern |
| plato-engine-block-c | C99 | Embedded reference: zero heap alloc, bare-metal portable |
| plato-engine-block-elixir | Elixir | BEAM supervision trees, fault tolerance, hot reload |
| plato-runtime-kernel | Rust | Spatial model: tensor grid, batons, assertion traps |
| Repo | Language | Description |
|---|---|---|
| categorical-agents | Rust | Category theory for agent composition (functors, naturality) |
| cuda-constraint-engine | CUDA/C | GPU constraint checking at 1B+ constraints/sec |
| grand-pattern-rs | Rust | Fibonacci dual-direction cellular graph architecture |
| lau-hodge-theory | Rust | Hodge decomposition, Betti numbers, spectral sequences |
| ternary-science | Rust | Experimental evidence for ternary intelligence, 5 conservation laws |
| Repo | Language | Description |
|---|---|---|
| construct-core | Rust | Layered trait system: bare-metal → alloc → async agent runtime |
| crab | Bash | Agent shell for repo entry/leave (MUD-room metaphor) |
| exocortex | Rust | Persistent cognitive substrate, S3-compatible memory |
| git-agent | Python | The repo IS the agent — autonomous lifecycle via Git |
| capitaine-1 | TypeScript | Git-native repo-agent, Cloudflare Workers heartbeat |
| codespace-edge-rd | Research | Codespace→Edge agent lifecycle and yoke transfer protocols |
| git-agent-codespace | DevContainer | One-click Codespace template for Git-Agent runtimes |
| Registry | Package | Install |
|---|---|---|
| PyPI | flux-vm |
pip install flux-vm |
| crates.io | fluxvm |
cargo add fluxvm |
| npm | flux-js |
npm install flux-js |
- 📖 AI-Writings — Philosophy, essays, and design rationale
- 📦 PACKAGES.md — Full package index
MIT