{"slug": "show-hn-framein-a-local-work-state-layer-that-keeps-ai-agents-in-context", "title": "Show HN: Framein – a local work-state layer that keeps AI agents in context", "summary": "Framein, a local work-state layer for AI agents, launched to keep task context across Claude, Codex, and Gemini. The tool maintains a shared contract, decision trail, and validation results, enabling model switching and challenge workflows without losing progress. It addresses agent stalls, blind spots, and context loss during handoffs.", "body_md": "# Keep onework frameacross Claude,Codex, and Gemini.\n\nStart with one agent, challenge it with another, switch when needed, and close the work with validation. Framein keeps a shared task contract, decision trail, risk state, validation results, and model-switch capsule beneath the agent harness you already use.\n\n``` bash\n# Start in the agent you already use.\n$ framein start \"add Google OAuth\"\ncontract set: preserve email login\nlead claude\n\n# Ask a different model for a bounded objection.\n$ framein challenge \"OAuth callback state in session\" --run\nreviewer codex\nverdict challenge\nrequired add nonce/state validation\nlead accepts required change\n\n# Switch when needed; close with validation.\n$ framein capsule gemini\nnext lead prepared from facts:\ncontract · diff · tests · decisions\n\n$ framein ship\nbuild ok · tests passed\nrisk high: auth/ touched\n=> READY WITH HUMAN GATE\n```\n\n## Challenge, verify, and hand offwithout losing context.\n\nA payment-task walkthrough showing a task contract, independent model challenge, validation evidence, and a capsule another agent can continue from.\n\n## Better prompts help.They do not keep the work intact.\n\nGood PRDs, plans, ADRs, and skills help any model do better work. The pain starts when the lead model stalls, another model should challenge the plan, quota or model fit pushes you to switch, or the final answer still needs real validation.\n\n**Framein is not a new IDE or another agent harness.** It keeps one local work frame under Claude Code, Codex, Gemini, Pi, OpenCode, and the skill workflows you already use.\n\nIf harnesses are the engine, Framein is the shared logbook the engines write to.\n\n**Stalled lead model** One agent keeps circling the same plan or failure mode.\n\n**One-model blind spots** Architecture, security, and test concerns need an outside model's view.\n\n**Reset on switch** Changing model often means explaining the same intent, risk, and decisions again.\n\n**Unverified finish** The last answer still needs build, tests, risk, and human gates before ship.\n\n## Start. Challenge.Switch. Validate.\n\n### Start\n\n`framein start`\n\nturns the request into a shared task contract before the implementation drifts.\n\n### Challenge\n\n`framein challenge`\n\nasks a different reviewer for a structured verdict, one lead response, and a decision brief.\n\n### Switch\n\n`framein capsule`\n\nprepares the next lead from local facts: contract, diff, validation, ADRs, and ledger.\n\n### Validate\n\n`framein verify`\n\nand `ship`\n\nclose the loop with deterministic build/test checks and risk gates.\n\n## Call it like a skill.Store it like project state.\n\n**Claude and Gemini slash commands**\n\n`/fr:*`\n\ncalls the same local engine from the agent session.\n\n**Codex project skills**\n\n`$fr-*`\n\nexposes the same verbs without deprecated prompt files.\n\n**Existing skill packs and personas**\n\nKeep your prompt framework. Framein supplies the shared contract, ledger, and gates underneath.\n\n**Terminal, CI, and MCP clients**\n\nThe CLI, JSON output, wrappers, and MCP server all read and write the same local work frame.\n\n## Install once.Keep the frame under your agents.\n\nInstall from npm, then initialize Framein inside a real project. In day-to-day use, agents can call the same work-frame verbs through `/fr:*`\n\nor `$fr-*`\n\n.\n\nThe npm path works across Windows, macOS, Linux, and WSL with Node 22.5+. Standalone executables are planned as an optional convenience path that bundles Node with Framein and avoids Windows npm shim friction.\n\n```\nnpm install -g framein\nframein --version\n\ncd your-project\nframein init\nframein integrations install all --write\n\nframein start \"complete the smallest safe change\"\n\n# when another model should review or continue\nframein challenge \"review the plan before implementation\" --run\nframein capsule codex\n\nframein verify\nframein ship\n```\n\n## Not a harness.Not a token relay.\n\n### Is this another harness?\n\nNo. Claude Code, Codex, Gemini, Pi, and OpenCode remain the working surface. Framein keeps the work state in your repo underneath them.\n\n### Does it touch provider tokens?\n\nNo. Framein collects no credentials, proxies no model traffic, and pools no subscriptions. Provider auth stays with the official CLI.\n\n### Where does state live?\n\nIn your repo: a git-friendly JSON snapshot plus a local SQLite cache. [Read the full FAQ](https://github.com/framein-dev/framein/blob/main/docs/FAQ.md).\n\n## Local first.No credential relay.\n\n### Local work frame\n\nTask contract, ADRs, memory, ledger, validation results, and write locks live in your repo. The SQLite store is a cache; the JSON snapshot is git-friendly.\n\n### No proxy layer\n\nFramein does not collect provider credentials, pool subscriptions, relay MCP tools, or screen-scrape terminal I/O (TTY). It calls official CLIs locally when you ask it to.", "url": "https://wpnews.pro/news/show-hn-framein-a-local-work-state-layer-that-keeps-ai-agents-in-context", "canonical_source": "https://www.framein.dev/", "published_at": "2026-06-30 12:36:49+00:00", "updated_at": "2026-06-30 12:50:20.915511+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Framein", "Claude", "Codex", "Gemini", "Pi", "OpenCode"], "alternates": {"html": "https://wpnews.pro/news/show-hn-framein-a-local-work-state-layer-that-keeps-ai-agents-in-context", "markdown": "https://wpnews.pro/news/show-hn-framein-a-local-work-state-layer-that-keeps-ai-agents-in-context.md", "text": "https://wpnews.pro/news/show-hn-framein-a-local-work-state-layer-that-keeps-ai-agents-in-context.txt", "jsonld": "https://wpnews.pro/news/show-hn-framein-a-local-work-state-layer-that-keeps-ai-agents-in-context.jsonld"}}