{"_id":"@ahoy-tools/anchor","_rev":"2-d6d339948d219171c60fde6f5e41da2b","name":"@ahoy-tools/anchor","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ahoy-tools/anchor","version":"0.1.0","keywords":["ai","agents","state","context","linter","llm","claude","gpt","recovery","context-switching"],"author":{"name":"Ahoy Tools"},"license":"MIT","_id":"@ahoy-tools/anchor@0.1.0","maintainers":[{"name":"boscoeuk","email":"ged.hughes@gmail.com"}],"homepage":"https://github.com/ahoy-tools/anchor#readme","bugs":{"url":"https://github.com/ahoy-tools/anchor/issues"},"bin":{"anchor":"bin/anchor.js"},"dist":{"shasum":"c3ddc1cadef8935e6282a096aed451260974b1fc","tarball":"https://registry.npmjs.org/@ahoy-tools/anchor/-/anchor-0.1.0.tgz","fileCount":9,"integrity":"sha512-mAtltot1WfH23BHUkmQhEm0JL1yGw23F9e+bspUzLGiIea+CNMZ6WhvUhq/M0tdswv9LfuYtecqU50qHQm4N/w==","signatures":[{"sig":"MEYCIQDleXzzHStjHmCt7ucqkSywfd46wTf2G2vuoAltFBAidQIhAL7ShA9hvmGPYTTmbrPf04EfjIDEOi28hU0lmcnRYz6x","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29277},"main":"src/linter.js","engines":{"node":">=14.0.0"},"gitHead":"fcffd342af469fbbbb1ad6e68208d1706ea4ca79","scripts":{"lint":"node bin/anchor.js","test":"node tests/linter.test.js","prepublishOnly":"npm test"},"_npmUser":{"name":"boscoeuk","email":"ged.hughes@gmail.com"},"repository":{"url":"git+https://github.com/ahoy-tools/anchor.git","type":"git"},"_npmVersion":"11.8.0","description":"State file linter for AI agents. 0% to 100% context recovery.","directories":{},"_nodeVersion":"25.5.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/anchor_0.1.0_1770373749592_0.48022602463026987","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2026-02-06T10:29:09.489Z","modified":"2026-07-20T17:46:02.089Z","0.1.0":"2026-02-06T10:29:09.739Z"},"bugs":{"url":"https://github.com/ahoy-tools/anchor/issues"},"author":{"name":"Ahoy Tools"},"license":"MIT","homepage":"https://github.com/ahoy-tools/anchor#readme","keywords":["ai","agents","state","context","linter","llm","claude","gpt","recovery","context-switching"],"repository":{"url":"git+https://github.com/ahoy-tools/anchor.git","type":"git"},"description":"State file linter for AI agents. 0% to 100% context recovery.","maintainers":[{"name":"boscoeuk","email":"ged.hughes@gmail.com"}],"readme":"# 🚀 Anchor\n\n**0% to 100% context recovery for AI agents**\n\nStop losing context. Stop rebuilding the wrong things. Stop wasting hours explaining what you were doing.\n\nAnchor is a state file linter that ensures AI agents can seamlessly resume complex tasks by validating the structure and content of state files.\n\n## The Problem\n\nAI agents lose context between sessions. They:\n- Build the wrong features \n- Forget critical decisions\n- Restart from scratch\n- Waste hours on confusion\n\n**Result:** Productivity drops to zero when agents can't recover context effectively.\n\n## The Solution\n\nA **state file format** + **linter** that guarantees successful context recovery.\n\n- 📝 **Structured state files** with resumption instructions\n- 🔍 **Automated linting** catches recovery-breaking issues  \n- 🎯 **Focus on \"what's next\"** instead of \"what's done\"\n- ⚡ **Works with any agent** (Claude, GPT, Cursor, etc.)\n\n## Quick Start\n\n```bash\n# Install globally\nnpm install -g @ahoy-tools/anchor\n\n# Initialize in your project  \nanchor init\n\n# Edit current-task.md with your task\n# Then lint it\nanchor lint current-task.md\n\n# Get fix suggestions\nanchor lint --fix current-task.md\n```\n\nThat's it. Your agents can now recover context 100% of the time.\n\n## Benchmark Results\n\nWe tested 4 different approaches to agent context recovery:\n\n| Trial | Method | Recovery Rate | Agent Behavior |\n|-------|--------|---------------|----------------|\n| **1** | Informal updates | **0%** | Confused, rebuilt wrong features |\n| **2** | Status-focused logs | **25%** | Better but missed critical context |  \n| **3** | Detailed documentation | **50%** | Good context, unclear resumption |\n| **4** | **Anchor protocol** | **🎯 100%** | **Perfect recovery every time** |\n\n**Key insight:** Agents need to know **WHERE TO RESUME**, not just what's been done.\n\n## The Format\n\n### ❌ Bad (causes 0% recovery)\n```markdown\n## Progress Update\nMade good progress on the auth system today.\n- Set up the database\n- Created some models\n- Authentication is mostly done\nWill finish tomorrow.\n```\n\n### ✅ Good (causes 100% recovery)  \n```markdown\n## 🎯 RESUME HERE\n\n**Next action:** Implement JWT middleware in routes/auth.js\n**Context:** Building task app. Database + models done. Auth routes need JWT protection.\n\n---\n\n## Progress\n- [x] Database connection established\n- [x] User/Task models created  \n- [ ] JWT middleware implementation ← YOU ARE HERE\n- [ ] Protected route testing\n- [ ] Frontend login integration\n```\n\n## CLI Commands\n\n```bash\n# Lint a state file\nanchor lint current-task.md\n\n# Show problems + fix suggestions\nanchor lint --fix current-task.md\n\n# Lint with detailed explanations  \nanchor lint --verbose current-task.md\n\n# Create example files\nanchor init\n\n# Show recommended format\nanchor format\n\n# Get help\nanchor --help\n```\n\n## Rules Reference\n\nAnchor checks for 8 critical issues:\n\n### 🚨 **Errors** (will cause recovery failures)\n\n- **Missing \"RESUME HERE\" section** - Agent won't know what to do next\n- **Resume section buried deep** - Should be in first 10 lines  \n- **Next action describes completion** - Should be actionable task, not status\n- **File too short** - Need at least 50 chars of context\n\n### ⚠️ **Warnings** (may cause issues)\n\n- **No explicit next action** - Be specific about what's next\n- **Ambiguous completion language** - Clarify what remains vs. what's done\n- **Missing context section** - Agent may lack essential background\n\n### 💡 **Info** (best practices)\n\n- **All checklist items checked** - Add remaining work if task ongoing\n\n## Integration Examples\n\n### Claude Code\nAdd to your project workflow:\n```bash\n# Before resuming work\nanchor lint current-task.md\n\n# Update as you progress  \n# Lint again before stopping\nanchor lint current-task.md\n```\n\n### Cursor\nAdd as a custom command in `.vscode/settings.json`:\n```json\n{\n  \"terminal.integrated.profiles.osx\": {\n    \"Anchor Lint\": {\n      \"path\": \"anchor\",\n      \"args\": [\"lint\", \"current-task.md\"]\n    }\n  }\n}\n```\n\n### Generic Agents\nInclude in system prompt:\n```\nBefore starting any task:\n1. Run: anchor lint current-task.md  \n2. Follow the \"Next action\" exactly\n3. Update state file as you progress\n4. Lint again before context switches\n```\n\n### CI/CD Integration\nAdd to GitHub Actions:\n```yaml\n- name: Lint state files\n  run: |\n    npm install -g @ahoy-tools/anchor\n    anchor lint *.md\n```\n\n## State File Template\n\nRun `anchor init` to create a complete template, or use this structure:\n\n```markdown\n## 🎯 RESUME HERE\n\n**Next action:** [Specific task to do RIGHT NOW]\n**Context:** [1-2 sentences of essential background]\n\n---\n\n## Progress\n- [x] What's done (with key details)\n- [ ] What's next\n- [ ] What comes after that\n\n## Original Task  \n[Full task description for reference]\n\n## Technical Notes\n[Key decisions, blockers, or discoveries]\n\n## Resources\n[Relevant links, docs, examples]\n```\n\n## Why It Works\n\n### Traditional approaches fail because:\n- ❌ Focus on **what's done** (status updates)\n- ❌ Bury resumption info in long documents  \n- ❌ Use ambiguous language (\"almost done\")\n- ❌ Lack specific next actions\n\n### Anchor succeeds because:\n- ✅ Focus on **what's next** (resumption)\n- ✅ Put critical info at the top\n- ✅ Enforce clear, actionable language\n- ✅ Validate structure automatically\n\n## API\n\nUse Anchor programmatically:\n\n```javascript\nconst { lintStateFile } = require('@ahoy-tools/anchor');\n\nconst results = lintStateFile('current-task.md');\n\nif (!results.passed) {\n  console.log('Errors:', results.errors);\n  console.log('Warnings:', results.warnings);\n}\n```\n\n## Contributing\n\nFound an issue? Have a rule suggestion? \n\n1. [Open an issue](https://github.com/ahoy-tools/anchor/issues)\n2. Describe the context recovery problem\n3. Suggest the rule or fix\n\n## License\n\nMIT © [Ahoy Tools](https://github.com/ahoy-tools)\n\n---\n\n**Stop losing context. Start with Anchor.**\n\n```bash\nnpm install -g @ahoy-tools/anchor\nanchor init\n```","readmeFilename":"README.md"}