The universal AI agent handoff tool. Never explain your codebase to a new agent again.
Your AI agent hits its context limit. A new session starts. The new agent has no idea what was done, what was decided, why, or what comes next. You spend 10 minutes re-explaining the project.
grwm fixes this. It generates a structured, token-budgeted handoff brief and broadcasts it to the native config format of every AI agent you use — simultaneously.
grwm handoffThis single command:
- Automatically refreshes your PyPI codebase static graph if Graphify is installed.
- Reads your task board state, decision log, git branch, commits, and diff pointer.
- Compiles a structured, token-optimized brief targeting ≤ 2,000 tokens.
- Writes it to the native config format of every detected AI agent.
The next agent, in any tool, finds the briefing in its expected location and starts immediately with full context.
Completely eliminate manual typing! Running grwm autolog automatically parses your uncommitted changes (git diff) and recent commits to dynamically extract completed tasks and technical decisions:
- Free OpenCode DeepSeek V4 Flash (Default): Integrates natively with OpenCode's public keyless gateway to route prompts directly to the free model
deepseek-v4-flash-free. Zero API keys or token costs required! - Deep Graphify Mapping: If a Graphify static graph exists in your project (
graphify-out/graph.json),autologextracts the most central architectural components (highest-degree nodes) and feeds them into the DeepSeek prompt to map your changes precisely to existing modules! - Resilient Local Heuristics Fallback: Works 100% offline. If the gateway is unreachable, a robust offline regex engine cleans commit prefixes (like
feat:,fix:) and scans commit bodies for design decisions to update your logs instantly.
| Agent / IDE | File written by grwm handoff |
|---|---|
| Claude Code | .claude/CONTEXT.md |
| Cursor | .cursor/rules/grwm-handoff.mdc |
| Windsurf | .windsurf/rules/grwm-handoff.md |
| GitHub Copilot | .github/copilot-instructions.md |
| Cline | .cline/rules/grwm-handoff.md |
| Aider | CONVENTIONS.md |
| Gemini Code Assist | .gemini/grwm-context.md |
| OpenAI Codex | .codex/grwm-context.md |
| Continue | .continue/grwm-context.md |
| All agents | AGENTS.md (always, universal standard) |
npm install -g @sankalpasarkar/grwm# 1. Initialize in your project
grwm init
# 2. Add tasks manually, or let grwm scan your workspace automatically
grwm add "implement auth module"
# 3. Work on your codebase and commit changes...
# 4. Automatically extract context and update tasks/decisions
grwm autolog
# 5. Log manual technical decisions as they happen
grwm log "chose JWT over sessions — stateless required for multi-server"
# 6. When context hits ~60%, generate handoff (updates graphify in the background!)
grwm handoff
# 7. In the new agent session, resume instantly
grwm resume| Command | Description |
|---|---|
grwm init |
Initialize .trail/ and write startup instructions to all detected agent configs (with interactive Graphify setup) |
grwm autolog |
Automatically extract uncommitted diffs and Git history into completed tasks and decisions using free Big Pickle or offline local heuristics |
grwm add <title> |
Add a new task (status: queued) |
grwm log <decision> |
Append a decision to the append-only decision log |
grwm done <task> |
Mark task done. --files "a.ts,b.ts" to record touched files |
grwm blocked <task> |
Mark task blocked. --reason "..." to document why |
grwm handoff |
Compile brief + broadcast to all detected agents (auto-runs Graphify in background if installed) |
grwm handoff --agent cursor |
Write only to Cursor |
grwm handoff --index-sessions |
Include Claude Code session analysis (needs ANTHROPIC_API_KEY) |
grwm resume |
Print handoff brief (run at session start) |
grwm status |
Show task board and recent decisions |
grwm keys |
Manage AI provider API keys interactively (add, update, remove, test, custom endpoints) |
Add this to your project's AGENTS.md so every new agent session automatically loads the handoff:
## Session startup
At the start of every new session, run:
grwm resume
Do not start work until you have read the handoff brief.
## Session end / handoff
Before ending a session or when context exceeds 60%:
grwm handoffgrwm init writes this automatically.
| Layer | What it reads | What it writes |
|---|---|---|
| L0 — Trigger | API token usage | Warn when context is at 60% |
| L1 — Git | Branch, commits, diff stat | Feeds brief |
| L2 — Graphify | graphify-out/graph.json (optional) |
Pointer in brief (auto-synced & injected into L6 prompt) |
| L3 — Tasks | .trail/tasks.json |
Task state (JSON, Zod-validated) |
| L4 — Decisions | .trail/decisions.md |
Append-only decision log |
| L5 — Sessions | ~/.claude/projects/ (opt-in) |
.trail/session-index.json |
| L6 — Brief | All layers | .trail/handoff.md |
| Broadcast | .trail/handoff.md |
All agent config files |
# grwm Handoff Brief — my-project
> Generated: 2026-06-02T17:30:00Z | Branch: `feature/payments` | Last commit: `a3b9f12`
## [CONTEXT_REF]
- Code graph: `graphify-out/graph.json` (287 nodes, 1,204 edges)
- Key nodes: PaymentService, AuthMiddleware, UserRepository
## [NEXT]
- **Implement refund flow** [queued]
## [IN_PROGRESS]
- Stripe webhook verification — handler added, need idempotency key check
## [DONE]
- ✓ Auth module (JWT, refresh tokens)
- ✓ User registration and login
- ✓ Basic Stripe checkout session creation
## [BLOCKED]
- ✗ Email notifications — **REASON**: SendGrid API key not provisioned
## [DECISIONS]
- [2026-06-02T14:22Z] chose Postgres over SQLite — need full-text search
- [2026-06-02T15:44Z] NOT using LangChain — too heavy for this use case
- [session] decided against microservices — monolith ships faster for MVP
## [CHANGED_FILES]
- `src/payments/webhook.ts`
- `src/payments/stripe.service.ts`
This is harness engineering, not prompt engineering. The key insight from Anthropic's own research:
"Context resets — clearing the context window entirely and starting a fresh agent with a structured handoff — is more effective than compaction. The new agent starts fresh with no context anxiety."
grwm automates the harness layer: writing structured artifacts to disk in real-time during the session. If the agent crashes mid-task, the next one can still resume cleanly.
MIT © sankalpasarkar