FossilRepo

fossilrepo / docs / api / agentic-development.md
Source Blame History 188 lines
45192ef… ragelink 1 # Agentic Development
45192ef… ragelink 2
45192ef… ragelink 3 FossilRepo is built for AI-assisted development at scale. Traditional Git forges impose rate limits that cripple agent workflows. FossilRepo eliminates these bottlenecks.
45192ef… ragelink 4
45192ef… ragelink 5 ## The Problem
45192ef… ragelink 6
45192ef… ragelink 7 AI coding agents make dozens of API calls per task. On GitHub:
45192ef… ragelink 8 - 5,000 API calls/hour limit (agents burn through this in minutes)
45192ef… ragelink 9 - 30 search requests/minute
45192ef… ragelink 10 - Webhook delivery delays
45192ef… ragelink 11 - Actions queue congestion
45192ef… ragelink 12
45192ef… ragelink 13 Multiple agents working in parallel hit rate limits within seconds.
45192ef… ragelink 14
45192ef… ragelink 15 ## The Solution
45192ef… ragelink 16
45192ef… ragelink 17 ```
45192ef… ragelink 18 AI Agent (Claude Code, Cursor, etc.)
45192ef… ragelink 19 |
45192ef… ragelink 20 v
45192ef… ragelink 21 FossilRepo MCP Server / API <-- zero rate limits
45192ef… ragelink 22 |
45192ef… ragelink 23 v
45192ef… ragelink 24 Fossil repos (.fossil SQLite) <-- local disk, instant
45192ef… ragelink 25 |
45192ef… ragelink 26 v (scheduled, batched)
45192ef… ragelink 27 Git Mirror --> GitHub <-- rate-limit-aware sync
45192ef… ragelink 28 ```
45192ef… ragelink 29
45192ef… ragelink 30 Agents work against FossilRepo locally with no limits. Changes sync to GitHub on a schedule. GitHub becomes a downstream mirror, not the bottleneck.
45192ef… ragelink 31
45192ef… ragelink 32 ## Connecting AI Tools
45192ef… ragelink 33
45192ef… ragelink 34 ### MCP Server (Recommended)
45192ef… ragelink 35
45192ef… ragelink 36 The MCP server gives AI tools native access to all FossilRepo capabilities.
45192ef… ragelink 37
45192ef… ragelink 38 ```bash
45192ef… ragelink 39 pip install fossilrepo
45192ef… ragelink 40 fossilrepo-mcp
45192ef… ragelink 41 ```
45192ef… ragelink 42
45192ef… ragelink 43 Claude Code config:
45192ef… ragelink 44 ```json
45192ef… ragelink 45 {
45192ef… ragelink 46 "mcpServers": {
45192ef… ragelink 47 "fossilrepo": {
45192ef… ragelink 48 "command": "fossilrepo-mcp"
45192ef… ragelink 49 }
45192ef… ragelink 50 }
45192ef… ragelink 51 }
45192ef… ragelink 52 ```
45192ef… ragelink 53
45192ef… ragelink 54 17 tools available: browse code, read files, search, manage tickets, view timeline/diffs/blame, create tickets, run SQL queries.
45192ef… ragelink 55
45192ef… ragelink 56 ### JSON API
45192ef… ragelink 57
45192ef… ragelink 58 For tools without MCP support:
45192ef… ragelink 59 ```
45192ef… ragelink 60 curl -H "Authorization: Bearer frp_abc123..." \
45192ef… ragelink 61 http://localhost:8000/projects/myproject/fossil/api/timeline
45192ef… ragelink 62 ```
45192ef… ragelink 63
45192ef… ragelink 64 ### Batch API
45192ef… ragelink 65
45192ef… ragelink 66 Reduce round-trips by 25x:
45192ef… ragelink 67 ```json
45192ef… ragelink 68 POST /api/batch
45192ef… ragelink 69 {"requests": [
45192ef… ragelink 70 {"method": "GET", "path": "/api/timeline"},
45192ef… ragelink 71 {"method": "GET", "path": "/api/tickets", "params": {"status": "Open"}},
45192ef… ragelink 72 {"method": "GET", "path": "/api/wiki/Home"}
45192ef… ragelink 73 ]}
45192ef… ragelink 74 ```
45192ef… ragelink 75
45192ef… ragelink 76 ## The Agent Workflow
45192ef… ragelink 77
45192ef… ragelink 78 ### 1. Discover Work
45192ef… ragelink 79
45192ef… ragelink 80 Browse open, unclaimed tickets:
45192ef… ragelink 81 ```
45192ef… ragelink 82 GET /api/tickets/unclaimed
45192ef… ragelink 83 ```
45192ef… ragelink 84
45192ef… ragelink 85 ### 2. Claim a Ticket
45192ef… ragelink 86
45192ef… ragelink 87 Atomic claiming prevents two agents from working on the same thing:
45192ef… ragelink 88 ```
45192ef… ragelink 89 POST /api/tickets/<uuid>/claim
45192ef… ragelink 90 {"agent_id": "claude-session-abc"}
45192ef… ragelink 91 ```
45192ef… ragelink 92 Returns 200 if claimed, 409 if already taken by another agent.
45192ef… ragelink 93
45192ef… ragelink 94 ### 3. Create an Isolated Workspace
45192ef… ragelink 95
45192ef… ragelink 96 Each agent gets its own Fossil branch and checkout directory:
45192ef… ragelink 97 ```
45192ef… ragelink 98 POST /api/workspaces/create
45192ef… ragelink 99 {"name": "fix-auth-bug", "agent_id": "claude-session-abc"}
45192ef… ragelink 100 ```
45192ef… ragelink 101
45192ef… ragelink 102 No interference with other agents or the main branch.
45192ef… ragelink 103
45192ef… ragelink 104 ### 4. Do the Work
45192ef… ragelink 105
45192ef… ragelink 106 Read code, understand context, make changes, commit. All via MCP tools or API:
45192ef… ragelink 107 ```
45192ef… ragelink 108 POST /api/workspaces/fix-auth-bug/commit
45192ef… ragelink 109 {"message": "Fix null check in auth middleware"}
45192ef… ragelink 110 ```
45192ef… ragelink 111
45192ef… ragelink 112 ### 5. Submit for Review
45192ef… ragelink 113
45192ef… ragelink 114 ```
45192ef… ragelink 115 POST /api/reviews/create
45192ef… ragelink 116 {
45192ef… ragelink 117 "title": "Fix null pointer in auth module",
45192ef… ragelink 118 "description": "The auth check was failing when...",
45192ef… ragelink 119 "diff": "--- a/src/auth.py\n+++ b/src/auth.py\n...",
45192ef… ragelink 120 "workspace": "fix-auth-bug"
45192ef… ragelink 121 }
45192ef… ragelink 122 ```
45192ef… ragelink 123
45192ef… ragelink 124 ### 6. Review and Merge
45192ef… ragelink 125
45192ef… ragelink 126 Another agent (or human) reviews:
45192ef… ragelink 127 ```
45192ef… ragelink 128 POST /api/reviews/<id>/approve
45192ef… ragelink 129 POST /api/reviews/<id>/merge
45192ef… ragelink 130 ```
45192ef… ragelink 131
45192ef… ragelink 132 ### 7. Release the Claim
45192ef… ragelink 133
45192ef… ragelink 134 ```
45192ef… ragelink 135 POST /api/tickets/<uuid>/submit
45192ef… ragelink 136 {"summary": "Fixed by closing the null check gap"}
45192ef… ragelink 137 ```
45192ef… ragelink 138
45192ef… ragelink 139 ## Real-Time Coordination
45192ef… ragelink 140
45192ef… ragelink 141 ### Server-Sent Events
45192ef… ragelink 142
45192ef… ragelink 143 Agents subscribe to a live event stream instead of polling:
45192ef… ragelink 144 ```
45192ef… ragelink 145 GET /api/events
45192ef… ragelink 146 ```
45192ef… ragelink 147
45192ef… ragelink 148 Events:
45192ef… ragelink 149 - `checkin` — new commits pushed
45192ef… ragelink 150 - `claim` — ticket claimed or released
45192ef… ragelink 151 - `workspace` — workspace created, merged, or abandoned
45192ef… ragelink 152
45192ef… ragelink 153 ### Multi-Agent Safety
45192ef… ragelink 154
45192ef… ragelink 155 FossilRepo prevents agent collisions through:
45192ef… ragelink 156
45192ef… ragelink 157 1. **Atomic ticket claiming** — database-level locking via `select_for_update`. Only one agent can claim a ticket.
45192ef… ragelink 158 2. **Isolated workspaces** — each agent works on its own Fossil branch in its own checkout directory. No merge conflicts during work.
45192ef… ragelink 159 3. **Code review gate** — changes must be reviewed (by human or another agent) before merging to trunk.
45192ef… ragelink 160 4. **Branch protection** — protected branches block non-admin pushes. CI status checks can be required.
45192ef… ragelink 161 5. **SSE events** — agents know what others are doing in real-time, avoiding duplicate work.
45192ef… ragelink 162
45192ef… ragelink 163 ## Comparison with GitHub
45192ef… ragelink 164
45192ef… ragelink 165 | Feature | GitHub | FossilRepo |
45192ef… ragelink 166 |---------|--------|------------|
45192ef… ragelink 167 | API rate limit | 5,000/hour | Unlimited |
45192ef… ragelink 168 | Search rate limit | 30/min | Unlimited |
45192ef… ragelink 169 | Agent workspace | Shared branch | Isolated checkout |
45192ef… ragelink 170 | Task claiming | None (race conditions) | Atomic (DB-locked) |
45192ef… ragelink 171 | Batch API | None | 25 calls/request |
45192ef… ragelink 172 | Real-time events | Webhooks (delayed) | SSE (instant) |
45192ef… ragelink 173 | Code review | Pull request (heavyweight) | Lightweight API |
45192ef… ragelink 174 | MCP support | No | 17 tools |
45192ef… ragelink 175 | CI status API | Rate-limited | Unlimited |
45192ef… ragelink 176 | Self-hosted | No | Yes |
45192ef… ragelink 177 | Cost | Per-seat | Free (MIT) |
45192ef… ragelink 178
45192ef… ragelink 179 ## Why Fossil for Agents?
45192ef… ragelink 180
45192ef… ragelink 181 Fossil's architecture is uniquely suited for agentic development:
45192ef… ragelink 182
45192ef… ragelink 183 - **Single-file repos** — each `.fossil` file is a complete SQLite database. No complex storage, no git pack files, no network dependencies.
45192ef… ragelink 184 - **Built-in everything** — tickets, wiki, forum, technotes all in one file. Agents manage the full development lifecycle without switching tools.
45192ef… ragelink 185 - **SQLite = instant reads** — FossilReader opens the file directly. No API calls, no HTTP, no rate limits. Microsecond latency.
45192ef… ragelink 186 - **Offline-first** — works without internet. Sync to GitHub when ready, on your schedule.
45192ef… ragelink 187 - **Clone = complete backup** — `fossil clone` gives you everything: code, tickets, wiki, forum. One file, one copy.
45192ef… ragelink 188 - **Branching without overhead** — Fossil branches are lightweight metadata, not separate directory trees. Creating 50 agent workspaces costs nothing.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button