momentum

Your AI coding agent forgets. Hit the context limit or start a fresh session and it loses the roadmap, the architecture decisions, the bug it fixed an hour ago. momentum makes your project’s memory durable — phases, decisions, history, and backlog live as plain files your agent reads at the start of every session and updates as it works. Whether your agent ships code, manages infrastructure, runs research, or operates pipelines, the same discipline applies: every phase planned, every decision recorded, every release tagged. State that outlives any single session.

npx @avinash-singh-io/momentum@latest init

Copy

How it works — no daemon, no lock-in

momentum isn’t a framework or a background service. It’s plain files and conventions your agent already knows how to read.

1. init writes files into your repo — your agent’s instruction file (CLAUDE.md / AGENTS.md), a specs/ folder, rule and slash-command definitions, and git hooks.
2. Your AI IDE already reads that instruction file every session — momentum just fills it with a structured workflow and a map of where project state lives.
3. Your agent maintains the state as it works — it reads status.md to orient, logs decisions to history.md, and tracks work in backlog.md. Automatically.

Nothing runs in the background. Uninstall = delete the files.

Works with any AI IDE

Same commands, same workflow, every agent. Brings momentum's discipline into whichever IDE your team already uses.

• Claude Code CLAUDE.md Available
• Codex AGENTS.md Testing pending
• Antigravity AGENTS.md Testing pending
• Cursor .cursor/rules/ Planned
• Gemini CLI GEMINI.md Planned

What you get

Open-source primitives your agent uses to keep your project's state coherent across days, branches, and sessions.

• Phases

  Plan, execute, verify, release. Every phase is a unit of work with a brainstorm, plan, tasks, and history.

• Backlog

  Bugs, features, tech debt, and enhancements with priorities and per-item context.

• History

  Append-only log of decisions, discoveries, and scope changes. The "why" outlives any session.

• Rules

  Thirteen autonomous agent rules — orient first, verify before claim, log every decision.

• Skills

  Slash commands your agent runs automatically — start, complete, sync, review, validate.

• Ecosystem

  Coordinate multiple related projects from one agent session — opt-in, additive.

The 13 rules

Discipline preserved — without enforcement overhead.

Thirteen autonomous behaviors your agent follows in the background. Three of the highest-leverage:

1. Rule 6

   Git Lifecycle

   Feature branch auto-created. Conventional commits. Push silently. NEVER merge to main without your explicit OK.

2. Rule 8

   Record Phase History

   Every meaningful decision, discovery, or scope change lands in history.md the moment it happens. The "why" outlives every session.

3. Rule 12

   Verify Before Claim

   No completion without evidence. Run the test, read the output, mark done only if the output shows pass. Closes the most common "should work now" failure mode.

All 13 rules with full text + red flags →

15+ slash commands

Your agent already knows how to drive this.

Phases, backlog, history, doc-sync — all run as slash commands. Three of the most-used:

• /brainstorm-phase

  Plan the next phase through structured dialogue. Disk writes blocked until you approve.

  						> /brainstorm-phase
  
  Reading specs/status.md... Phase 12 just completed.
  Checking backlog... no P0 blockers.
  
  What's the goal of this phase? (one question at a time)
  > _
  					

• /start-phase

  Begin implementation. Autonomous execution per the contract — stops only at merge + release gate.

  						> /start-phase
  
  Creating branch phase-13-site-polish...
  Updating status.md... Current Phase → 13.
  Group 0: Mermaid tooling + baseline...     ✓
  Group 1: Landing rewrite...                ✓
  Group 2: Docs deepening...                 ✓
  ...
  					

• /complete-phase

  Verify, finalize, tag, publish. The receipts (Rule 12 evidence) get captured into retrospective.md.

  						> /complete-phase
  
  Running verification:
    npm test         → 246/246 ✓
    linkinator       → 0 broken ✓
    lighthouse       → 98/96/100/100 ✓
  
  Tagging v0.16.0. npm publish? (y/N) _
  					

Browse all 15+ skills →

Built for the way you work

Solo builder

Your project doesn't forget what it was building when you stepped away for a week. Pick up exactly where you left off, with the agent already oriented.

Tech lead

Bring discipline to agentic AI work across your team. Every decision logged, every phase planned, every release tagged — without enforcement overhead.

PM exploring agentic AI

Read the why behind every decision your engineers' agents make. Phases, decisions, and history are first-class artifacts, not lost in chat transcripts.

When one repo isn’t enough

Single-project usage is the default — everything above works in one repo with zero extra setup. When you have related repos that need to coordinate, ecosystem mode lets one agent session work across all of them — no context switching, full ecosystem awareness, every member’s per-repo discipline preserved.

Across multiple projects

Orchestration.

Three layers that coordinate work across your projects: Ecosystem (shared state on disk), Cross-project actions (one-shot moves), and Swarm (sustained multi-step delivery). Both upper tiers read and write the foundation underneath.

Sustained delivery

Swarm

Drive a whole cross-project feature end-to-end from ONE session. Conductor + per-project supervisors, wave-ordered, multi-hour. Survives session kill via disk-only resume.

• Conductor + supervisors, cwd-pinned per project
• Wave ordering from ecosystem.json dependencies
• Persistent saga state — manifest + board + inbox + contracts
• 95% token saving via materialized board cache

Read the swarm guide →

One-shot actions

Cross-project actions

Four single-step verbs the agent runs per task. One move and done — no persistent state, no waves.

• scout — read state from one project
• dispatch — fan out work across N projects
• handoff — transfer control to another session
• continue — pick up an inbox

See the four actions →

Foundation — shared data

Ecosystem

Shared state on disk that both tiers above read and write. No verbs — just durable substrate.

• ecosystem.json — members + dependency edges
• initiatives/ — cross-project feature tracking
• sessions/ — daily session log auto-recording commits
• pointer blocks in each member project

Read the ecosystem deep dive →

Which one do I use?

Match your situation to the verb.

Orchestration's three layers, one decision: pick by what you're trying to do. Cross-project actions for one-shot moves. Swarm for sustained, dependency-ordered, multi-step work. Both read and write the ecosystem data layer underneath.

Your situation	Use	Reads / writes	Layer
Looking up state in one project	scout	read-only	Action
Asking a question or running work across N projects, one shot	dispatch	read or write	Action
Pausing here and letting another session pick up	handoff	writes	Action
Finding what is waiting for you	continue	read-only	Action
Driving a coordinated feature across N projects — multi-hour, dependency-ordered	swarm	writes	Swarm
Recording a cross-project effort so future sessions find it	initiative	writes	Ecosystem