🏃 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):

Time impact (measured across 10 sessions):

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:

Commands Reference

sprint-agent init [options]

Initialize .sprint/ directory with templates and agent config.

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.

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

sprint-agent backlog add <description> [options]

Add a prioritized ticket to the backlog.

sprint-agent backlog add "Fix auth redirect loop" --priority P1 --effort S
sprint-agent backlog add "Add E2E Playwright tests" --priority P2 --effort L --sprint S03
sprint-agent backlog add "Security audit" --priority P0 --effort XL

Other commands

Configuration

# .sprint/config.yaml — edit to customize
project:
  name: "My SaaS App"

sprint:
  duration: 7              # calendar days per sprint
  days_per_sprint: 5       # working days
  daily_duration: 30       # minutes per session
  retro_day: friday
  start_day: monday

agent:
  type: auto               # auto | claude | cursor | copilot | aider | windsurf

priorities:
  P0: "Critical — blockers, security, data loss"
  P1: "High — must ship this sprint"
  P2: "Medium — next sprint"
  P3: "Low — this quarter"
  P4: "Nice-to-have — someday/maybe"

effort:
  XS: "< 30 min"
  S:  "~1 hour"
  M:  "2-4 hours (1 daily)"
  L:  "4-8 hours (2-3 dailies)"
  XL: "> 1 day (break it down)"

What Gets Generated

AGENT.md (read by AI at session start)

# AI Agent Instructions — Sprint Agent

## Your Workflow (every session)
1. Read this file
2. Read `.sprint/sprints/` latest file
3. Pick the next TODO ticket
4. Work for 30 minutes
5. Update the sprint file
6. Commit with ticket ID

## Rules
- 1 daily = 1 ticket (unless XS)
- Verify deploys after push
- Document blockers in sprint file
- Friday = retrospective

## Project Context
> (you add your project details here)

Sprint file (one per week)

# Sprint S03 — Week of 2026-01-19

> Goal: Launch auth + payment
> Capacity: 5 x 30min = 2.5h

## Monday — DONE
- [x] T-012: Fix auth redirect loop

## Tuesday — TODAY
- [ ] T-013: Add Stripe checkout flow

## Wednesday
- [ ] T-014: Webhook signature verify

## Metrics
| Metric | Start | End   |
|--------|-------|-------|
| Tests  | 45    | 52    |

Retrospective (every Friday)

# Retrospective S03 — 2026-01-23

## 1. What went well
- Auth flow shipped in 2 dailies

## 2. What didn't go well
- Stripe webhook took longer than expected

## 3. Actions for next sprint
- [ ] Add webhook retry logic
- [ ] Write E2E tests for payment

## 4. Score
- Productivity: 4/5

Real-World Results

Battle-tested building DataFrancePro — a B2B SaaS platform with 5M+ French companies:

6 sprints. 70+ tickets. 1 developer. 30-minute daily sessions.

Philosophy

1. Markdown over databases — .md files readable by humans AND AI agents
2. Convention over configuration — Opinionated defaults, override what you need
3. Agent-first design — Optimized for AI context windows, not human dashboards
4. Git-native — Sprint history is version-controlled; diffs show progress
5. Zero dependencies — Pure Python stdlib; your sprint files work without Sprint Agent installed
6. Single-file distribution — One .py file = standalone tool OR pip package

Why I built this

I was burning 20-40% of every Claude Code session watching the agent re-discover my codebase. Same files. Same conclusions. Every time.

So I tried the obvious thing: write down what's done, what's next, what failed — in a file the agent reads first. Token cost dropped 83%. Time-to-first-edit dropped from 8-15 min to 2 min.

The unlock was treating the AI agent like a teammate who joined yesterday: give them a sprint board, not a tabula rasa. After 6 sprints and 70+ shipped tickets on DataFrancePro, this workflow became how I ship.

Open-sourcing it because the format works for any agent, any project, any solo dev. — Miloud

Roadmap

Sprint Agent stays small. Here's what's planned:

• sprint-agent ticket done <id> — mark a ticket as done from CLI
• sprint-agent burnup — burnup chart in the terminal
• sprint-agent stats — sprint velocity and trend over time
• Pre-built .sprint/ templates for common stacks (Next.js, FastAPI, Rails)
• Optional sprint-agent watch — auto-sync on file changes
• Companion VSCode/Cursor extension (separate repo, keeps core single-file)

Vote with thumbs on the discussions board — most-requested ships first.

Contributing

See CONTRIBUTING.md. TL;DR:

git clone https://github.com/miloudbelarebia/sprint-agent
cd sprint-agent
python sprint_agent.py --help    # test locally
python sprint_agent.py init      # test init

Issues and PRs welcome: github.com/miloudbelarebia/sprint-agent/issues

License

MIT — see LICENSE.

Built by Miloud Belarebia.
Battle-tested on DataFrancePro — 5M+ companies, 70+ tickets, 6 sprints, 1 developer + Claude Code.