🏃 sprint-agent

Turn any AI agent into an agile developer. Persistent sprint context for Claude Code, Cursor, Copilot, Codex, Gemini, Aider, Windsurf. 83% fewer tokens per session. Zero dependencies. Pure Python.

🌐 Website: miloudbelarebia.github.io/sprint-agent

Sprint Agent gives AI coding agents persistent memory and structured workflow — so they stop wasting tokens re-reading your codebase and start shipping like a teammate.

---

The Problem

Every time you start a new session with an AI agent, it wastes time re-reading your entire codebase:

                WITHOUT Sprint Agent

  Session 1          Session 2          Session 3
  ┌────────────┐    ┌────────────┐    ┌────────────┐
  │ ░░░░░░░░░░ │    │ ░░░░░░░░░░ │    │ ░░░░░░░░░░ │
  │ Read 50    │    │ Read 50    │    │ Read 50    │
  │ files      │    │ files      │    │ files      │  WASTE
  │ again      │    │ again      │    │ again      │
  │ ░░░░░░░░░░ │    │ ░░░░░░░░░░ │    │ ░░░░░░░░░░ │
  │            │    │            │    │            │
  │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │
  │ Actual     │    │ Actual     │    │ Actual     │  WORK
  │ work       │    │ work       │    │ work       │
  └────────────┘    └────────────┘    └────────────┘

  Context: ~12,300 tokens wasted per session
  No memory between sessions
  Agent doesn't know what was done yesterday

                WITH Sprint Agent

  Session 1          Session 2          Session 3
  ┌────────────┐    ┌────────────┐    ┌────────────┐
  │ ░░ sprint  │    │ ░░ sprint  │    │ ░░ sprint  │  2 min
  │            │    │            │    │            │
  │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │
  │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │
  │ ▓▓ Actual ▓ │    │ ▓▓ Actual ▓ │    │ ▓▓ Actual ▓ │  WORK
  │ ▓▓ work   ▓ │    │ ▓▓ work   ▓ │    │ ▓▓ work   ▓ │
  │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │
  │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │    │ ▓▓▓▓▓▓▓▓▓▓ │
  └────────────┘    └────────────┘    └────────────┘

  Context: ~2,100 tokens (83% reduction)
  Full memory: what's done, what's next, what failed
  Agent picks up exactly where it left off

---

Installation

Two ways — same tool, your choice:

# Option A: pip (recommended)
pip install sprint-agent
sprint-agent init

# Option B: standalone (zero install, drop-in single file)
curl -O https://raw.githubusercontent.com/miloudbelarebia/sprint-agent/main/sprint_agent.py
python sprint_agent.py init

Why two modes? The pip path is the standard developer experience. The standalone path is for restricted environments (corporate firewalls, ephemeral CI runners, air-gapped boxes) where pip install isn't an option — drop one .py file in the repo and it just works.

---

Quick Start

# 1. Initialize in your project
sprint-agent init --name "My SaaS" --daily 30 --agent claude

# 2. Check today's status
sprint-agent status

# 3. Add tickets to the backlog
sprint-agent backlog add "Fix auth redirect" --priority P1 --effort S
sprint-agent backlog add "Add E2E tests" --priority P2 --effort L --sprint S03

# 4. Plan next sprint
sprint-agent sprint new --goal "Launch payment flow"

# 5. Friday retro
sprint-agent retro

# 6. Save to git
sprint-agent sync

After init, your project gets a .sprint/ directory:

your-project/
├── .sprint/
│   ├── AGENT.md              ← AI agent reads this first (auto-loaded)
│   ├── backlog.md            ← Prioritized product backlog
│   ├── config.yaml           ← Sprint settings (daily duration, etc.)
│   ├── sprints/
│   │   └── S01_2026-01-05.md ← Weekly sprint with daily breakdown
│   ├── retros/
│   │   └── RETRO_S01.md      ← Friday retrospective
│   └── sessions/
│       └── (auto-created)
├── CLAUDE.md                 ← Auto-generated (Claude Code reads this)
└── .cursorrules              ← Auto-generated (Cursor reads this)

---

How It Works

  You                   Sprint Agent              AI Agent
   │                        │                        │
   │  sprint-agent init     │                        │
   │───────────────────────>│                        │
   │                        │  Creates .sprint/      │
   │                        │  + AGENT.md            │
   │                        │  + backlog.md          │
   │                        │  + sprint S01          │
   │                        │                        │
   │  "Start working"       │                        │
   │────────────────────────────────────────────────>│
   │                        │                        │
   │                        │   Reads .sprint/ ──────│
   │                        │                        │
   │                        │   Knows instantly:      │
   │                        │   ● Sprint S03, Day 2   │
   │                        │   ● 3/8 tickets done    │
   │                        │   ● Next: fix auth bug  │
   │                        │   ● Blocker: DB migrate  │
   │                        │                        │
   │                        │   Works 28 min ────────>│
   │                        │   Updates sprint ──────>│
   │                        │                        │
   │   "Done for today"     │                        │
   │<────────────────────────────────────────────────│
   │                        │                        │
   │  sprint-agent sync     │                        │
   │───────────────────────>│  git commit + push     │
   │                        │                        │

---

The Token Cost — Real Numbers

Measured on DataFrancePro (5M company database, 70+ tickets, 6 sprints):

| What the agent reads | Without | With Sprint Agent | |---------------------|---------|-------------------| | Instructions file | 6,200 tokens | 200 tokens | | Session history | 5,100 tokens | 0 (in sprint) | | State/status file | 1,600 tokens | 0 (in sprint) | | Sprint file | — | 1,900 tokens | | Total context | ~12,300 | ~2,100 | | Reduction | | 83% |

Time impact (measured across 10 sessions):

| Metric | Without | With | Gain | |--------|---------|------|------| | Context loading | 8-15 min | 2 min | 4-7x faster | | Work time / 30min | 15-22 min | 28 min | +50% | | Repeated exploration | Every session | Never | Eliminated |

Methodology: Personal benchmark, single developer (me) on DataFrancePro. Tokens at ~4 bytes/token. Time = session start to first code edit. 10 daily sessions, April 2026. Before = no agile structure. After = Sprint Agent. Your numbers will vary depending on project size, codebase complexity, and existing context discipline. Treat the 83% as a directional reference, not a guarantee.

---

The Agile Model

Sprint Agent implements lightweight agile for solo dev + AI agent pairs:

┌──────────────────── WEEK ─────────────────────┐
│                                                │
│  Mon      Tue      Wed      Thu      Fri       │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐ │
│  │DAILY│  │DAILY│  │DAILY│  │DAILY│  │RETRO│ │
│  │ 30m │  │ 30m │  │ 30m │  │ 30m │  │ 15m │ │
│  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘ │
│                                                │
│  Daily = status + 1 ticket + update            │
│  Retro = review + plan next week               │
│                                                │
│  Total: 2h15 focused work per week             │
│  Result: 5-10 tickets shipped per sprint       │
└────────────────────────────────────────────────┘

The Sprint Cycle

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ BACKLOG  │────>│  SPRINT  │────>│  DAILY   │────>│  RETRO   │
│          │     │          │     │          │     │          │
│ All work │     │ This week│     │ Today's  │     │ Review   │
│ P0 → P4  │     │ 5-8      │     │ ticket   │     │ Score    │
│ Icebox   │     │ tickets  │     │ 30 min   │     │ Improve  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
     │                │                │                │
     v                v                v                v
 backlog.md      sprint.md      sprint.md [x]     retro.md

---

Agent Compatibility

Works with any AI coding agent that reads project files:

| Agent | Auto-config file | How it works | |-------|-----------------|--------------| | Claude Code | CLAUDE.md | Auto-read at session start | | Cursor | .cursorrules | Auto-read at session start | | GitHub Copilot | .github/copilot-instructions.md | Manual read | | Aider | .aider.conf.yml | Manual read | | Windsurf | .windsurfrules | Auto-read at session start | | OpenAI Codex | AGENTS.md | Auto-read at session start | | Gemini | — | Tell it: "Read .sprint/AGENT.md" | | Any agent | — | Tell it: "Read .sprint/AGENT.md" |

---

Commands Reference

sprint-agent init [options]

Initialize .sprint/ directory with templates and agent config.

| Option | Default | Description | |--------|---------|-------------| | --name <name> | directory name | Project name | | --daily <min> | 30 | Daily session duration (minutes) | | --days <n> | 5 | Working days per sprint | | --retro-day <day> | friday | Retrospective day | | --agent <type> | auto | claude cursor copilot codex gemini aider windsurf | | --force | — | Overwrite existing .sprint/ |

sprint-agent init                                    # defaults: 30min, 5 days
sprint-agent init --daily 45 --days 4                # custom schedule
sprint-agent init --name "My SaaS" --agent claude    # named project
sprint-agent init --daily 120 --days 2 --retro-day sunday  # weekend warrior

sprint-agent status

Show today's context: date, sprint, progress bar, remaining tickets.

╔══════════════════════════════════════════════╗
║          Sprint Agent — Daily Status          ║
╠══════════════════════════════════════════════╣
║  Date    : 2026-01-14 (Wednesday)            ║
║  Sprint  : S03  (day 3/5)                    ║
║  Progress: ████████████░░░░░░░░░░░░░ 48%     ║
║  Daily   : 30 min session                    ║
╚══════════════════════════════════════════════╝

Remaining tickets:
  ○ P2-01: Add rate limiting to /api/search
  ○ P2-02: Mobile responsive dashboard

sprint-agent sprint new [options]

Create the next weekly sprint.

| Option | Default | Description | |--------|---------|-------------| | --goal <text> | TBD | Sprint goal | | --daily <min> | from config | Override daily duration | | --days <n> | from config | Override working days |

sprint-agent sprint new --goal "Launch MVP auth + payment"

sprint-agent backlog add <description> [options]

Add a prioritized ticket to the backlog.

| Option | Default | Description | |--------|---------|-------------| | --priority <P0-P4> | P2 | Priority level | | --effort <XS-XL> | M | Effort estimate | | --sprint <id> | — | Assign to sprint (e.g. S03) |

spr