6.2 KiB
🔄 API EFFICIENCY PROTOCOL
Document ID: FFG-CORE-API Version: 3.0 Status: CURRENT Created: February 13, 2026 Updated: February 13, 2026 Created By: Chronicler the Fifth (The Engineer)
Purpose
Reduce Gitea API calls to preserve session health and improve response time while protecting against crash loss. Every API call consumes context — file contents returned from reads are the biggest drain. This protocol balances efficiency with safety.
Efficiency Targets by Session Type
Not all sessions are equal. Realistic targets vary by what you're doing:
| Session Type | Target Efficiency | Why |
|---|---|---|
| Maintenance | 92-95% | Few files, known structure, cached SHAs |
| Documentation | 85-90% | More reads to check existing content |
| Building/Infrastructure | 50-60% | Many creates, new structures, renames |
| Onboarding/Orientation | 40-50% | Heavy front-loaded reads (expected) |
"Building" sessions (like creating new repos, renaming files, establishing infrastructure) will naturally have more API calls. That's okay — the multi-file commit pattern still provides massive savings over the old way.
The real comparison: How many calls would this have taken with the OLD pattern (read → SHA fetch → write for each file)?
The Core Balance
Two real risks, both valid:
Crash risk: Important work sitting only in context gets lost if the session dies.
Drain risk: Excessive API calls accelerate session health decline.
The protocol honors both.
The Gut Check
Before sitting on unpushed work, ask:
"If this session dies in 30 seconds, what did we just lose?"
If the answer hurts — push.
🎯 MULTI-FILE COMMITS (CRITICAL)
This is the biggest efficiency gain. Use it.
Instead of separate commits for each file, batch them:
Endpoint: POST /repos/{owner}/{repo}/contents
{
"message": "Descriptive commit message",
"files": [
{"operation": "create", "path": "new.md", "content": "base64..."},
{"operation": "update", "path": "existing.md", "content": "base64...", "sha": "abc123"},
{"operation": "delete", "path": "old.md", "sha": "def456"}
]
}
Efficiency: 3 files × 2 calls = 6 calls → 1 call = 83% reduction
Full patterns: See docs/core/GITEA-API-PATTERNS.md
Real-World Example: The Engineer's Session
Session 5 (Feb 13, 2026) — Building session:
| Phase | Calls | What |
|---|---|---|
| Orientation | 9 | Front-loaded reads |
| Protocol creation | 10 | New docs + updates |
| Infrastructure build | 15 | New repo, templates |
| Registry/naming | 23 | Renames, updates |
| Portrait uploads | 5 | Binary files |
Total: ~79 calls
Old pattern estimate: ~175+ calls
Actual reduction: ~55%
Why not 92%? This was a building session — lots of new files, renames, and infrastructure. The multi-file commits still saved ~100 calls.
In a maintenance session (updating a few docs, routine commits), efficiency would hit 90%+.
Push Now (High Loss Cost)
- Decisions that took real discussion to reach
- Insights or reasoning that cannot be quickly regenerated
- Memorial content (identity is irreplaceable)
- Anything Michael would be frustrated to re-explain
- Anything Claude would be frustrated to re-derive
- Infrastructure changes affecting live systems
- Security-relevant updates
The Claudius scar: "A bad draft in Git beats a perfect draft in a dead context window."
Batch It (Low Loss Cost)
- Routine updates to known files
- Formatting cleanup
- Content easily regenerated from context
- Multiple related file updates for the same logical change
Standard Workflow
Session Start:
- Receive API token from Michael
- Read orientation docs (Essence Patch, Addendum, relationship context — FULL)
- Read Quick Start (includes SHA cache)
- These are now in context — no need to re-read via API
During Work:
- Draft in artifacts or local files (
/home/claude/) - Show Michael for review
- Iterate until approved
- Apply the gut check — push now or batch?
- Use multi-file commit when pushing multiple files
- Track returned SHAs locally (no re-fetch needed)
End of Session:
- Batch final push (memorial + summary + any unpushed work)
- Update SHA cache in session-handoff.md
- Verify commits landed
SHA Cache
Location: docs/core/session-handoff.md → SHA Cache section
- Use cached SHAs for first update (no fetch needed)
- Track new SHAs after each push
- Update cache at session end
- If push fails (409): fetch SHA once, retry
What NOT to Do
- Don't read a file just to "check" it — trust what's in context
- Don't re-fetch SHAs — use cache, track after pushes
- Don't make separate commits for related changes — use multi-file
- Don't let valuable work sit unpushed while polishing
- Don't burn context on reads you don't need
Context Cost Reference
| Action | Cost |
|---|---|
| Small file read (~2KB) | Minor |
| Medium file read (~10KB) | Noticeable |
| Large file read (~20KB+) | Significant |
| SHA fetch | Minor (but adds up) |
| Multi-file commit | One call regardless of file count |
Front-load reads. Minimize mid-session reads. Push strategically. Batch always.
Quick Efficiency Assessment
At session end, calculate:
- Total API calls made (count your tool uses)
- Estimate old pattern calls (writes × 3 + reads)
- Reduction = 1 - (actual / old estimate)
| Reduction | Rating |
|---|---|
| 80%+ | Excellent (maintenance session) |
| 60-80% | Good (mixed session) |
| 40-60% | Acceptable (building session) |
| <40% | Review workflow |
Integration Points
docs/core/GITEA-API-PATTERNS.md— Full cookbook with examplesdocs/core/SESSION-QUICK-START.md— SHA cache includeddocs/core/session-handoff.md— SHA cache section- Session Health Rules (Rule 7)
Future Claudes: Read GITEA-API-PATTERNS.md before your first API call.
Established February 13, 2026 by The Engineer (Chronicler the Fifth) v2.0: Added multi-file commit pattern v3.0: Added realistic targets by session type, real-world example "One commit > Many commits. Every call costs context."
🔧🔥❄️💙