FossilRepo

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

Keyboard Shortcuts

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