Universal AI Context Harness
Stop explaining your code to rebooted AI agents.
AI agents lose context when limits are hit or sessions reset. Stop manual copy-pasting—use grwm to instantly sync structured, token-optimized briefs directly to their instructions.
Universal Broadcast Engine
Write once, deploy everywhere. Compiled briefs are instantly translated and safely broadcasted into native rules formats for Cursor, Windsurf, Claude Code, Cline, Copilot, Aider, and standard AGENTS.md.
L2 Code Graphing (Graphify)
Deep codebase mapping with the PyPI graphifyy skill. Extracts core god nodes, maps complex communities, and targets a massive 71.5x token compression. Completely offline, secure, and blazing fast.
AI-Powered Autologging
Zero-manual-typing tracking. Run grwm autolog to instantly extract completed tasks and design decisions from uncommitted changes, using free OpenCode DeepSeek V4 Flash or offline heuristics.
Idempotent and Safe
No bricked configs or overwritten project rules. grwm relies on smart <!-- grwm:handoff:start --> markers to update instructions inline without touching your personal configurations.
Purely Local & Secure
Zero telemetry. Zero external server syncs. All tasks, decisions, and handoff markdown files live inside your local .trail/ folder. Complete repository security, natively.
Next-Gen Zod Validation
Strict JSON schema validation for all queued, in-progress, blocked, and done tasks. State files remain 100% corruption-free, even if you crash your terminal mid-run.
Getting Started in 60 Seconds
grwm is exceptionally simple. Here is the absolute quickest way to hook up your AI assistants:
# 1. Install grwm globally
npm install -g @sankalpasarkar/grwm
# 2. Go to your project directory and initialize
grwm init
# 3. Queue up some features you need to build
grwm add "integrate Stripe checkout"
grwm add "implement JWT middleware"
# 4. Do some work. Did you make an architectural decision? Log it immediately!
grwm log "JWT is stored in HTTPOnly cookie to prevent XSS leaks"
# 5. Your AI hit context limits or started behaving weirdly? Time to reset!
grwm handoff
# 6. Fire up a fresh AI prompt or IDE session and kick it off:
grwm resume
# 7. Alternatively, let AI automatically extract completed tasks and decisions from Git:
grwm autolog
Quick Tip: The moment you run grwm init, grwm automatically populates startup context instructions inside Cursor rules, Windsurf Cascade custom rules, Claude Code's CLAUDE.md, Cline, Aider, and a universal AGENTS.md file! The next AI agent automatically knows to look for it.
CLI Reference Index
Run these commands from anywhere in your project workspace directory.
| Command | Options | Description |
|---|---|---|
grwm init |
— | Sets up .trail/ and inserts bootstrap loaders into all detected IDE/agent rule systems. |
grwm autolog |
— | Automatically extracts uncommitted diffs and Git history into completed tasks and decisions using free DeepSeek V4 Flash or offline local heuristics. |
grwm add <title> |
— | Appends a new task to your state file under the queued column. |
grwm log <decision> |
— | Inserts a permanent, timestamped decision in the append-only markdown log. |
grwm done <task> |
--files "a.ts,b.ts"--notes "desc" |
Bumps a task to done. Optionally records files modified and notes to pass as context. |
grwm blocked <task> |
--reason "blocker" |
Marks a task blocked and records the reason so the next agent doesn't waste tokens trying to solve it. |
grwm handoff |
--agent <name>--graph--install-graphify--index-sessions |
Performs token optimization, prints a summary, and broadcasts the handoff markdown globally. |
grwm resume |
— | Prints the full handoff brief compiled during the last session. Extremely clean. |
grwm status |
— | Prints an interactive ASCII board showing your current state, blockers, and recent decisions. |
grwm keys |
— | Launches the interactive CLI to manage AI provider API keys (add, update, remove, test, custom endpoints). |
The 6-Layer Context Harness
grwm operates on a multi-layer stack to synthesize the ultimate developer environment handoff:
Trigger System
Alerts you immediately when token budget usage reaches critical limits (typically 60-70%), signalling it's time to run grwm handoff.
Git Integration
Extracts current active branches, recent uncommitted changes, git diff statistics, and checkout logs to feed the AI context pool.
Graphify indexing
Reads codebase static graph details. Detects core structural points (god nodes, community edges) without wasting millions of tokens on raw files.
Task Board (JSON)
Pulls queued, in-progress, blocked, and completed tasks from local JSON files, maintaining persistent, clean workspace state.
Decision Log (Markdown)
Collects architectural trade-offs, tech choice explanations, and logical design constraints recorded by developers during sprints.
Session Mining (Opt-in)
Mines previous AI agent shell terminal logs (e.g. Claude Code session profiles) to pull dynamically negotiated choices that occurred in chat.
Configuration Specification
When running grwm init, a local configuration is provisioned under .trail/config.json. You can customize the behavior easily:
{
// The maximum token budget allowed for the handoff brief
"maxHandoffTokens": 2000,
// Custom output location for graphify integration
"graphifyPath": "graphify-out/graph.json",
// Automatically pull Claude session files on every handoff
"autoIndexSessions": false,
// Custom file formats to ignore during git diff context building
"ignoreGlobs": ["*.log", "package-lock.json", "node_modules/**"]
}Be serious. It's a completely local-first, zero-dependency, open-source context harness. No API keys are required (unless you're mining Claude sessions). We make zero external calls, we do not ship your code to random databases, and we have zero interest in selling you tokens. It is literally built to automate writing markdown configs so your AI agent stops acting like it has amnesia. Period.
It stands for Get Ready With Me. You know, like those viral TikTok vlogs where people get ready for the day? It's the same energy — but you're prepping your AI agent with all the tasks, decisions, git history, and code graphs it needs before sending it to war in your codebase. Clean, visual, high-signal preparation.
Yes. That is the entire magic. Cursor looks at .cursor/rules/ on every query. Windsurf reads .windsurf/rules/. Claude Code natively consumes CLAUDE.md on startup. Cline, Copilot, Aider, and Continue all have native, built-in paths they automatically look at. grwm handles the pain of formatting and broadcasting the brief directly to all of them at once. No prompt engineering needed.
If you run grwm handoff --install-graphify, it pip-installs the awesome open-source package graphifyy, runs graphify ., and analyzes the resulting knowledge graph. It looks at the highest-degree "god nodes" (the classes and methods holding your architecture together) and lists them in the handoff brief. Plus, it auto-runs during handoff and feeds these nodes directly into your autologging AI context! It is actually insane value.
Out of the box: Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, Aider, Gemini Code Assist, OpenAI Codex, and Continue. And if you use a custom tool, it writes a universal AGENTS.md file that any model can consume directly. Compatibility is a non-issue.
Yes, 100%! grwm integrates natively with OpenCode's public keyless gateway to request the free model deepseek-v4-flash-free directly (zero keys or registration needed). If your network is offline, grwm's regex engine falls back gracefully to Git parsing. No AI slop, no expensive API fees. Pure context engineering.
Upgrade your context engineering game.
Zero bloat, zero telemetry, infinite developer velocity. Stop explaining, start coding.