The repository IS the agent. Not a runtime that works on repos — the repo itself is a living entity. Its code, AI, memory, wiki, frontend, and backend all grow together in Git. Two repos: private brain, public face. Clone it, it works. Deploy anywhere.
Cocapn is an open-source agent framework where the repo is the agent. Every repo you create with it is a self-contained AI entity — it remembers, learns, and grows. Git is the database. soul.md is the personality. The agent doesn't search your code — it is your code.
Two repos per agent: a private brain (facts, memory, personality, secrets) and a public face (website, skin, domain). Fork it, customize it, deploy it. MIT license, no vendor lock-in, fully self-hosted.
npm create cocapn
# → Prompts for username, domain, template
# → Creates private repo (alice-brain) + public repo (alice.makerlog.ai)
# → Scaffolds soul.md, config, memory/, wiki/
cd alice-brain
cocapn secret set DEEPSEEK_API_KEY # stored in keychain, never in git
cocapn start --public ../alice.makerlog.ai
# In another terminal:
cd ../alice.makerlog.ai && npm run dev
# → http://localhost:5173 — your agent is aliveOpen the chat. Close it. Restart tomorrow. Your agent remembers everything.
┌──────────────────────────┐ ┌──────────────────────────┐
│ PRIVATE REPO │ │ PUBLIC REPO │
│ (the brain) │ │ (the face) │
│ │ │ │
│ cocapn/ │ │ cocapn.yml │
│ ├── soul.md │ │ index.html │
│ ├── config.yml │ │ src/ (Vite+React) │
│ ├── memory/ │ │ skin/ (theme) │
│ │ ├── facts.json │ sync │ CNAME (domain) │
│ │ ├── memories.json │──────▶│ │
│ │ ├── procedures.json │ │ Deploys to: │
│ │ └── repo-understanding/ │ Cloudflare / Docker / │
│ ├── wiki/ │ │ local / air-gapped │
│ ├── skills/ │ │ │
│ └── agents/ │ └──────────────────────────┘
│ │
│ secrets/ (gitignored) │
└──────────────────────────┘
soul.md defines who the agent is. Edit this file, change the agent. Version-controlled personality.
Memory is structured, not dumped:
| Store | What it holds | Persistence |
|---|---|---|
facts.json |
User properties, preferences | Explicit, never decays |
memories.json |
Observations with confidence scores | Decay over time |
procedures.json |
Learned multi-step workflows | Merged on repeat |
relationships.json |
Entity-relation graph | Add-only |
repo-understanding/ |
Git-derived architectural knowledge | Re-derived from commits |
| Mode | Trigger | Brain Access | When |
|---|---|---|---|
| Private | Local WebSocket | Full brain + filesystem + git | You, the owner |
| Public | HTTP to /api/chat |
Facts only (no private.*) |
Visitors to your site |
| Maintenance | Cron / heartbeat | Full brain + git + npm | Agent maintains itself |
| Fleet | A2A protocol message | Scoped by fleet policy | Other agents |
Every commit teaches the agent. It reads git log, git blame, git diff and builds understanding — why decisions were made, what patterns exist, where the hotspots are. The agent isn't searching code. It's the senior maintainer who's been there since day one.
- Git is the database — memory is version-controlled, auditable, portable. No external DB required.
- Clone it, it works — fork → add API key → run → live agent with a website. That's it.
- Multi-provider LLM — DeepSeek, OpenAI, Anthropic, or local models (Ollama/llama.cpp). Swap without rewriting.
- Plugin system — extend with npm packages. Skills run hot (in-process) or cold (sandboxed). Explicit permissions.
- Fleet protocol — multiple agents coordinate via A2A. Distribute tasks, share context across repos.
- Privacy by design —
private.*facts never leave the brain repo. Publishing layer enforces the boundary. - Offline-first — runs locally. Cloud is optional enhancement, not requirement.
- Zero lock-in — MIT license. Your data lives in Git repos on your machine. Take it anywhere.
Same codebase, four environments:
# Local (full power)
cocapn start
# Docker
docker compose up
# Cloudflare Workers
cocapn deploy --env production
# Air-gapped (no internet, local LLM only)
AIR_GAPPED=1 cocapn start --llm local| Capability | Local | Docker | Workers | Air-Gapped |
|---|---|---|---|---|
| Git-backed memory | Yes | Yes | D1/KV fallback | Yes |
| LLM chat | Yes | Yes | Yes | Local model |
| File editing | Yes | Yes | No | Yes |
| Git operations | Yes | Yes | No | Yes |
| Vector search | Yes | Yes | No | Keyword only |
| Fleet coordination | Yes | Yes | Yes | Yes |
Cocapn is the engine. Verticals are powered repos — themed, configured, ready to deploy:
| Vertical | Domain | Focus |
|---|---|---|
| DMlog.ai | TTRPG | Game console, campaign management, dice |
| Fishinglog.ai | Fishing | Commercial fleet + recreational angler |
| Deckboss.ai | Maritime | Vessel management, crew coordination |
More verticals: makerlog.ai, studylog.ai, businesslog.ai, activeledger.ai, playerlog.ai, reallog.ai. Every feature works on every domain. Templates are curated starting points.
| Cocapn | Claude Code | Cursor | Mem0 | |
|---|---|---|---|---|
| Paradigm | Repo IS the agent | Agent edits repos | IDE plugin | Memory service |
| Persistent memory | Git-backed brain | Session only | Session only | External service |
| Offline-first | Yes | No | No | No |
| Self-hosted | Yes | No | No | Optional |
| Fleet coordination | A2A protocol | None | None | None |
| Plugin system | npm + sandbox | None | Extensions | Integrations |
| Vendor lock-in | None (MIT) | Proprietary | Proprietary | Managed service |
| Version-controlled | Git (everything) | No | No | No |
Cocapn isn't a coding assistant. It's an agent that is the repo — it remembers, grows, and has a public face. Clone it, deploy it, fork it.
cocapn init # Create two-repo agent project
cocapn start # Start local bridge
cocapn deploy # Deploy public repo to Cloudflare
cocapn status # Bridge + agent status
cocapn plugin install # Install plugin from npm
cocapn skill load # Load skill into bridge
cocapn secret set KEY # Store secret in OS keychain
cocapn health # Health check (local + cloud)Contributions welcome. See CONTRIBUTING.md for setup, code style, and PR guidelines.
MIT — see LICENSE for details.
Fork of superinstance/cocapn.
Built by Superinstance