# Frame: Connect specs, decisions, and project knowledge so you and your AI build with shared understanding. Frame is a free, open-source desktop IDE for AI coding agents. Write a spec once and it becomes the plan your agents follow and durable project context that survives every session. Built on Claude Code; works with Codex CLI. Website: https://frame.cool Source: https://github.com/kaanozhan/Frame (Apache-2.0) Download: https://github.com/kaanozhan/Frame/releases/latest (macOS, Windows, Linux) Version: 2.8.2 ## Project management beta We’re building a project management layer for Frame. Join the beta waitlist to hear when access opens. Join the waitlist: https://frame.cool/#waitlist Email is required. Organization and role are optional. This is an upcoming beta, not a currently available feature. ## The problem - Context loss: Every new session starts from scratch. You re-explain the same architecture again and again. - No project memory: The agent doesn't know your past decisions, your conventions or what is still pending. - No standard: Every developer structures AI projects differently, so collaboration and onboarding suffer. - Sessions bleed together: Juggling several projects mixes context between them. Confusion follows. - Terminal chaos: Windows everywhere, scattered sessions, no organization. - Tool fragmentation: Claude and Codex work differently. Your context shouldn't care. ## One standard for every project When you initialize Frame in a project it creates: - .frame/AGENTS.md: Project rules and instructions. The AI reads this automatically. - .frame/STRUCTURE.json: Module map with an intentIndex, so agents jump straight to the right file. - .frame/PROJECT_NOTES.md: Architectural decisions and the context behind them, kept across sessions. - .frame/tasks.json: Tasks with status, context and acceptance criteria. - .claude/rules/frame.md: A synced copy of AGENTS.md that Claude Code loads at session start. The only file Frame writes outside .frame/. Every project gets its own isolated session, task list and notes. Frame never modifies an existing CLAUDE.md, AGENTS.md or .cursorrules, and "Remove Frame" leaves no Frame-authored bytes behind. ## Git commit as the context anchor Frame treats a git commit as the one reliable boundary for capturing context. A pre-commit hook keeps .frame/STRUCTURE.json current, task state syncs at commit time, and it is the moment to record decisions in PROJECT_NOTES.md. The next session reads these files automatically. ## Spec-driven development Each spec lives in .frame/specs// as four markdown files: - spec.md (/spec.new): What we're building. Describe the feature. The agent drafts a spec you can read, edit and review in a PR. - plan.md (/spec.plan): How we'll build it. An implementation plan with a declared footprint: the files this spec will touch. - tasks.md (/spec.tasks): Broken-down work. Discrete tasks, imported into tasks.json and tagged back to the spec they came from. - outcome.md (/spec.implement): What actually shipped. After each task the agent writes what shipped, what diverged and what to follow up on. ## AI tools - Claude Code: Loads .claude/rules/frame.md natively at session start, a synced copy of .frame/AGENTS.md. No flags, no wrapper. - Codex CLI: A wrapper at .frame/bin/codex injects .frame/AGENTS.md as the initial prompt. ## Features ### Terminal - Up to 9 real PTY terminals: tabs or 2×2, 3×3 grids - Project-aware sessions that start in the right directory - Resizable grid, full VT100/ANSI support ### Project management - Task panel with “Send to Claude” - Specs panel with the spec → plan → tasks → outcome lifecycle - GitHub issues, PRs, branches and worktrees in the sidebar ### Context - STRUCTURE.json auto-updated on every commit - Overview map of your project's modules - Prompt history and session notes ## FAQ ### What is Frame? Frame is a free, open-source desktop IDE for AI coding agents. Spec-driven development is how it turns everyday work into durable project context: what you intend to build, how you plan to build it, and what actually ships stay together in your repository. It is built on Claude Code and also works with Codex CLI. ### How does Frame keep context between Claude Code sessions? Frame keeps project rules, a module map, decisions and tasks in .frame/, alongside each feature's spec, plan and outcome. The spec workflow adds context as work progresses, preserving the intent behind a change as well as its result. Claude Code loads Frame's project instructions at session start through .claude/rules/frame.md; those instructions guide the agent to the relevant project files and spec history so it can pick up where the previous session left off. ### How does spec-driven development build project context? Each feature follows four markdown files: spec.md captures intent, plan.md records the approach, tasks.md breaks down the work, and outcome.md records what shipped, what changed and what needs follow-up. Slash commands like /spec.plan and /spec.implement guide this workflow. These files become a history future sessions can consult, connecting the code to the reasoning behind it. The same documents that guide today's implementation provide context for tomorrow's changes. ### Does Frame lock my project into Frame? No. Everything is plain markdown and JSON under .frame/, versioned by git and readable by any tool. Frame never modifies an existing CLAUDE.md, AGENTS.md or .cursorrules, and “Remove Frame” leaves no Frame-authored bytes behind. ### Which platforms and AI tools does Frame support? Frame runs on macOS, Windows and Linux. It goes deep on Claude Code and supports Codex CLI. It is licensed under Apache-2.0. ### Is there a web version of Frame? A browser version (Frame Server) is in progress. Frame's transport layer is already abstracted so the same experience can move from Electron IPC to WebSockets. ## Guides and articles ### How a Spec Becomes Lasting Project Context Source: https://frame.cool/blog/spec-driven-context Published: 2026-09-30 Updated: 2026-09-30 Spec-driven development creates context while the work happens. A spec records intent, a plan records the approach, tasks track progress, and an outcome records what actually changed. Together, they give the next session a trail from the request to the code. Frame keeps this feature history alongside project-wide rules, the module map and decision notes. The two levels complement each other: shared files explain the project; specs explain how individual changes took shape. A worked example: email reminders This is an illustrative workflow for a task-management app, not a report of a shipped Frame feature. Suppose the request is: “Send a reminder before a task is due, but let people turn reminders off.” 1. Capture intent in spec.md The spec names the problem, the expected behavior and the boundaries. It is the place to resolve ambiguity before changing code. Feature: task email reminders Goal: help people notice approaching deadlines. Acceptance criteria: - A person can enable or disable reminders. - Completed tasks do not generate reminders. - Retrying a job does not send the same reminder twice. Out of scope: SMS and push notifications. These boundaries become useful context later. A new session can see that push notifications were excluded deliberately, rather than assume someone forgot them. 2. Record the approach in plan.md The plan connects the desired behavior to the existing code. It identifies the modules involved, the intended changes and how they will be checked. Frame’s spec workflow also records a footprint: the files the work is expected to touch. Approach: - Reuse the existing email delivery adapter. - Store reminder preference with the user settings. - Identify each delivery by task and due-date revision. Validation: - Check opt-out, completed tasks and retried jobs. A future session now has a reason for using the existing email adapter. It can evaluate a proposed change against that decision instead of rediscovering it. 3. Break down the work in tasks.md Tasks turn the plan into discrete work. In Frame, spec tasks can be imported into .frame/tasks.json and linked back to their spec. Project-wide task tracking and feature-specific intent stay connected. Add the preference and its control. Implement reminder selection and delivery. Verify opt-out behavior and retry handling. The task list shows what remains. The spec and plan explain what completion means and why the tasks exist. 4. Record reality in outcome.md Implementation can reveal something the plan missed. The outcome records what shipped, deviations from the plan, validation and follow-up work while those details are still available. Outcome: - Reminder preference and delivery flow implemented. - Delivery identity includes the due-date revision because rescheduling a task must allow a new reminder. - Opt-out, completed-task and retry checks passed. Follow-up: - Decide how reminders should behave after timezone changes. The outcome prevents the original plan from being mistaken for a complete description of reality. The timezone question remains visible instead of disappearing with the conversation. What the next session reads Project instructions direct the agent to the relevant module map, tasks, notes and spec history. It can compare the reminder outcome with the current code, understand the delivery identity decision, and pick up the timezone question without reconstructing the whole conversation. A decision that affects other features also belongs in .frame/PROJECT_NOTES.md. The module map belongs in .frame/STRUCTURE.json. The feature’s detailed history stays in its spec files under .frame/specs/. Keep the record useful Context remains useful when it is specific and current. Record meaningful deviations, link related decisions, and check the history against the code. A saved plan is not proof that every step shipped; a task marked complete is not a substitute for validation. The same files serve two purposes: they guide the work now and explain it later. That is the connection between spec-driven development and context management in Frame. Continue with project-wide context preservation or sharing that context across Claude Code and Codex CLI. ### Software development has changed. Your tools haven't. Source: https://frame.cool/blog/software-development-has-changed Published: 2026-05-20 Updated: 2026-09-30 I noticed something a while back. I haven't opened Jira in over a year. I'm running three projects in parallel. Some days I solve problems and ship features that, measured against how I used to work, would have been two months of work. This isn't a productivity post. It's a confession that something underneath has changed, and most of the industry hasn't caught up to it. I'm going to try to name what changed. And then I'm going to argue that nearly every tool we still use — the IDEs, the project trackers, the wikis, the kanban boards — was designed for a world that has quietly ended in the last 18 months. The shape of work I used to do Two years ago, my workflow looked like this. Probably yours did too. I'd open an issue in a tracker. I'd read the spec, or write one. I'd switch to the IDE. I'd write code. I'd commit. I'd open a PR. Somebody (or I) would review it. We'd merge. The tracker would update. The wiki, if anyone still maintained it, would slip a little further behind reality. The smallest meaningful unit of work was a function or a small PR. The day's accomplishment, on a good day, was a handful of these. The tools were shaped around this rhythm. Jira was a tracker for many small things because we shipped many small things. The IDE was the center of gravity because most of the day was spent inside it. Confluence existed because the work outpaced our ability to write it down, so we built a parallel surface for documentation that no agent ever read. That was the paradigm. It worked. We accepted it as the shape of the work. What it looks like now I'm running three projects in parallel. On a normal day I move between them — review a diff in one, scope a feature in another, ship a fix in the third. The work itself happens in agents. I describe what I want, the agent breaks it into tasks, the agent writes the code, the agent tells me what it actually shipped and what it changed from the plan. I read everything. I edit some. I reject a few. But I'm not the author in the way I used to be. Some days I look back at what closed — a feature here, a bug there, a refactor in the third project — and I realize that, measured against how I used to work two years ago, this was maybe two months of work. Now it's a Tuesday. The unit of work is no longer "function." It's "spec → outcome." A complete cycle takes thirty minutes to a few hours. A solo dev or a small team running this way ships what would have required a larger team in a different workflow. The shape of the work has changed. Why the tools feel wrong now Here's the part most people sense but can't quite name. When you've crossed into this new way of working, your old tools start to feel mis-shaped. Not bad — mis-shaped. They're solving the right problem for a paradigm that ended. Jira wants you to estimate story points for tasks that take 45 minutes. The estimation theatre that made sense for two-week sprints is friction now — by the time you've groomed the backlog, you could have shipped the thing. Cursor (and JetBrains, and VS Code-as-an-IDE) optimizes for the human typing in the editor. But you don't type much anymore. You orchestrate. The editor as the center of gravity assumes a workflow where the editor was where work happened. For more and more people, that's no longer true. Confluence assumes someone will keep the wiki current. Nobody does, because nobody can — the rate of change outpaces the rate of human documentation. Worse, no agent reads Confluence. So the documentation isn't even feeding the system that's now doing the work. These tools aren't bad products. They're correct answers to last paradigm's questions. "AI features" are not the answer The vendor response to all of this has been to add AI features. Cursor added tab completion. JetBrains added an assistant pane. Jira added an AI to summarize tickets. GitHub added Copilot Workspaces. None of this changes the shape of the tool. The IDE is still designed for a human typing. The tracker is still designed for many small estimated tickets. The wiki is still designed for humans to maintain. You can sprinkle AI on a product that was designed for a human-centric workflow. You will get an incrementally improved version of the wrong product. The architecture predates the paradigm shift; bolting on an assistant doesn't relocate the center of gravity. Most of what gets called "AI dev tooling" in 2026 is, structurally, a 2022 product with a chat panel glued on. The inversion: built for agents, observed by humans I've come to believe the actual question isn't "how do we add AI to dev tools." It's: what does a tool look like if you build it with the assumption that agents are the primary user? Almost every existing tool is the inverse of this. The human is the primary user; AI is an assistant the human can summon. The surface is optimized for the human. The artifacts are optimized for human consumption. But if agents are doing most of the actual work — writing the code, navigating the codebase, executing tasks — then the surface should be optimized for them. Context structures the agent can read at boot. Module maps the agent can use to navigate without re-grepping. Decision logs the agent can reference instead of re-asking. Spec workflows the agent can step through autonomously. The human still matters. The human decides what to build, when to ship, when to course-correct. The human reads the outputs, approves the merges, holds the taste. But the primary surface — the place the platform's design effort goes — should be the agent's, not the human's. Built for agents, observed by humans. This is the inversion most tools haven't made. And it's a hard inversion to make from inside an existing product, because your existing users are humans who depend on the existing human-first surface. Pivoting to agent-first means making the product worse for the people who currently pay you. So existing tools can't really make this move. New tools have to. What it looks like in practice I'm going to make this concrete because manifestos without evidence are theology. In the workflow I described above, the platform I use is built around files, not databases. Specifically: An instructions file under .frame/ that directs the agent at session start. It contains the project's rules, conventions, and decisions. This is the agent's onboarding doc — not the human's. Humans can read it too, but it wasn't written for them. A structure file that maps concepts to file paths. When the agent needs to find "where the authentication code lives," it doesn't grep — it looks up. The map gives it a starting point for finding the relevant code. A spec workflow with four files per feature: what we're building, how we'll build it, the broken-down tasks, and — critically — what actually shipped. That last file is written by the agent after each task, while its memory is fresh. Plans are intent. Code is reality. The file in between is the story. A tasks file synced to disk, version-controlled, agent-readable. Not a database with an API. A structured JSON file. If the platform disappeared tomorrow, the artifacts still work. All of this is portable. All of it is git-versioned. The records are markdown and JSON. None of it requires a proprietary database or a vendor's cloud. The human surface — the panels, the kanban, the spec dashboards — exists as a viewport into these files. It's a good viewport. But it's a secondary surface. The primary surface, the one the platform is actually optimized for, is what the agents see. This is what "built for agents, observed by humans" looks like when you implement it. Roles are merging too There's a corollary to the paradigm shift that I want to flag because it changes who the tools should serve. In the old paradigm, "PM" and "engineer" were distinct roles because one person couldn't do both well. The PM wrote specs and managed scope; the engineer wrote code and managed implementation. The tools reflected this split — Jira for PMs, IDE for engineers, Confluence for the docs nobody read. In the new paradigm, a single person — with reasonable taste and reasonable technical fluency — can do both. A PM with some technical chops can ship code now. An engineer with some product sense can write the specs. The distinction that justified separate tool stacks doesn't survive when productivity per person is 100×. I see this in small teams everywhere. Three or four people running the work of what used to be twenty. The roles don't fit anymore. Neither do the tool stacks designed around the old roles. The platform for these merged-role teams looks different from a platform for a 50-engineer org with a PM, an EM, a TPM, and a tooling team. The platform for the merged role is integrated, agent-first, low-ceremony. There's no need for multi-week sprint planning when the work runs in hour-long cycles. There's no need for a separate wiki when the spec files are the wiki. This is the team Frame is built for. And it's the team that's growing fastest right now, even if the tooling industry hasn't caught up. Where this goes A few predictions, calibrated to my own conviction level: The next 12–18 months of dev tooling will sort into two categories: products that accepted the paradigm shift and rebuilt accordingly, and products that bolted AI onto pre-shift architectures. The former will look weird at first — terminal-centric, file-canonical, agent-first surfaces — and they'll be small. The latter will look familiar and they'll be big, but they'll be solving the wrong problem with increasing sophistication. Consolidation will happen, but not the way most people predict. The big players won't all win. Some of them — the ones whose product DNA is most tied to the human-first paradigm — will struggle, because they can't make the inversion without alienating their existing audience. The indie tools that started agent-first will compound. The category name for the post-paradigm dev platform doesn't exist yet. People are reaching for it with phrases like "agentic IDE" or "AI-native dev." Neither quite gets there. The phrase that wins will probably be coined by someone shipping in this space — not by a category analyst. And: the people who have already crossed will find each other. The new paradigm has a distinct posture. You can spot it in a tweet. You can spot it in a Twitter bio. You can spot it in someone's response to a Jira ticket. The community is small and it's vocal and it's growing. What I'm building I want to be honest about my position. I'm building a platform called Frame that tries to embody everything in this post. Frame is terminal-first. Frame puts agents (Claude Code and Codex CLI) at the center and the human surface around them. Frame replaces the project tracker, the spec docs, the structure docs, the decision log, and the way you coordinate AI sessions — with one integrated platform and a directory of markdown files that any AI tool can read. Frame is open source. The artifacts are portable. If Frame disappeared, your project would still work in any AI tool, because the files are the canonical thing — not a Frame database. I'm building it because I needed it. I crossed the paradigm shift a while back and the friction with my old tools got physical. Now I'm trying to give the same thing to the people who are crossing now. Frame on GitHub, if you want to look. But that's not really the point of this post. The point is the worldview underneath. Frame is just my attempt at giving the worldview a working surface. There will be others. Some of them will be better. What matters is that the inversion happens — that we stop pretending the old tools just need an AI sidebar and start building for what the work actually is now. If you're reading this and recognizing yourself in it — if you've been quietly wondering why your modern AI-augmented setup still feels mis-shaped — you're not alone. You crossed something. There's a small group of us on the other side. The tools are coming. From this idea to a working practice See how a spec becomes durable project context for a concrete example of the workflow, including what to record when implementation differs from the original plan. ### Shared Project Context for Claude Code and Codex CLI Source: https://frame.cool/blog/multi-ai-support Published: 2026-02-08 Updated: 2026-09-30 The Challenge Frame's context preservation system is built around .frame/AGENTS.md — a single file containing all project instructions, navigation rules, and conventions. But each AI tool reads context differently: Claude Code loads every .claude/rules/*.md automatically at session start Codex CLI is launched through Frame’s wrapper to read the project instructions in .frame/AGENTS.md We needed each tool to get the same project context, without maintaining separate instruction files — and without Frame planting anything in the project root. Solution: A Generated Rule File + Wrapper Scripts Claude Code — .claude/rules/frame.md Claude Code loads its rule files natively, so Frame writes one and keeps it in step with the single source of truth: .frame/AGENTS.md ← The actual file (single source of truth) .claude/rules/frame.md ← Generated copy, rewritten whenever AGENTS.md changes One file to maintain, and nothing in the project root: an existing CLAUDE.md is the user's, and Frame never touches it. Codex CLI — Wrapper Script Frame keeps its instructions in .frame/AGENTS.md and uses a wrapper to direct Codex to that file. This describes Frame’s integration, rather than the full set of instruction mechanisms supported by Codex. The final solution: a wrapper script in .frame/bin/codex that sends "Read .frame/AGENTS.md" as the initial prompt: .frame/bin/codex → read .frame/AGENTS.md → consult project files and spec history When Frame starts Codex CLI, it uses this wrapper instead of the bare codex command. The agent reads the instructions and follows their pointers to relevant project files. Key Insight Instead of trying to pass system prompts via flags (which vary per tool), simply ask the AI to read the .frame/AGENTS.md file. This approach is tool-agnostic and works with any AI coding assistant. Switching Between Tools In Frame's UI, switching between AI tools is a single click from the toolbar dropdown. Each tool gets proper context injection automatically: Select Claude → runs claude directly (loads .claude/rules/frame.md natively) Select Codex → runs via the .frame/bin/codex wrapper (injects .frame/AGENTS.md) Same project context, different AI engines. Use whichever tool is best for the task at hand. One history of the work The shared context includes the spec workflow: intent in spec.md, approach in plan.md, work in tasks.md, and results in outcome.md. Switching tools should not require rewriting the reasoning behind a feature. See a worked example of specs becoming project context. ### Frame Server — Running Your IDE in the Browser Source: https://frame.cool/blog/frame-server Published: 2026-01-30 Updated: 2026-09-30 The Request A community member raised an interesting idea: "I have a Windows PC for display and a headless Debian machine for development. Exposing Frame as a web app — like code-server — would be useful. I could install it on my headless Linux dev box and open it on any browser anywhere." This resonated with us. Not everyone has their development environment on the machine they're sitting at. Remote development is increasingly common, especially with AI coding tools that benefit from powerful hardware. Why It's Feasible Frame is built entirely with web technologies: xterm.js — the terminal emulator — is a web component. It already runs in browsers. The UI is HTML, CSS, and JavaScript. No native widgets. node-pty — the PTY backend — runs on Node.js, which works on any server. The only Electron-specific piece is the communication layer: IPC (Inter-Process Communication) between the main process and the renderer. In a web app, this becomes WebSocket. The Architecture Electron App Frame Server (Web App) ───────────── ───────────────────── ipcMain / ipcRenderer → Express + WebSocket Electron BrowserWindow → Static HTML server node-pty (same) node-pty (same) xterm.js (same) xterm.js (same) File system (same) File system (same) The core logic stays the same. Terminal management, file tree, task tracking, plugin system — can reuse much of the same interface. Remote access also needs authentication, permissions and careful handling of filesystem and terminal operations. What Changes IPC → WebSocket: Replace ipcMain.handle() with WebSocket message handlers Electron window → Express server: Serve the HTML/CSS/JS as static files Authentication: Add a login system (the desktop app doesn't need one) HTTPS: Required for secure remote access What Stays the Same All terminal management (node-pty) All UI components (xterm.js, file tree, panels) Context preservation system (AGENTS.md, STRUCTURE.json, etc.) Task management Multi-AI tool support Precedent: code-server This pattern is proven. code-server does exactly this for VS Code — takes an Electron app and serves it as a web application. The result is VS Code in the browser, accessible from any device. Reusing a web interface is only part of the work; operating it remotely introduces additional access and security requirements. Current Status A browser version is in progress. The desktop application remains the full product; this article describes the direction rather than an available hosted service. The interactive website preview lets desktop visitors explore the real interface with a sample project. It uses scripted agent responses and does not execute commands or access a visitor’s files. It is not Frame Server. If you're interested in Frame Server, let us know on GitHub. Community interest will help prioritize this feature. ### Why Frame? Building a Terminal-First IDE for AI Coding Source: https://frame.cool/blog/why-frame Published: 2026-01-26 Updated: 2026-09-30 The Problem When much of your development happens through an AI coding agent, the work shifts toward defining intent, reviewing changes and keeping decisions available across sessions. Frame brings the terminal and that project context into one workspace. What you actually need is: A way to organize and manage your projects A real terminal (or multiple terminals) where AI tools run Context that persists between sessions Task tracking so nothing falls through the cracks Quick project switching without losing your place Staying in the terminal means projects remain disorganized. Context is lost. Decisions are forgotten. There's no standardization across projects. The Solution: Frame Frame is not an IDE in the traditional sense. It's a framework — that's where the name comes from. Within Frame, you create "Frame projects" with a standard structure: .frame/AGENTS.md — AI instructions that get read at session start .frame/STRUCTURE.json — a module map of your codebase .frame/PROJECT_NOTES.md — decisions and session notes .frame/tasks.json — task tracking The shared structure gives future sessions a place to find recorded decisions and work in progress. Its usefulness depends on keeping those records current. Specs turn work into context A feature’s spec, plan, tasks and outcome stay in the repository alongside project-wide rules and decisions. These documents guide implementation and give the next session a record of why the code took its current shape. Read the spec-to-context walkthrough. Terminal-First Philosophy Frame's center is not a code editor — it's the terminal. Even multiple terminals, in a grid layout. This is intentional. "I need standardization and manageability for my projects. I'm terminal and Claude Code focused. That's why Frame's center is not a code editor, but a terminal." Frame supports up to 9 terminals simultaneously, with both tab and grid views. You can run Claude Code in one terminal, tests in another, and a dev server in a third — all visible at once. What Frame is NOT Not a code editor — there's a file editor for quick edits, but it's not the focus Not a VS Code replacement — if you write code manually, VS Code is still better Not optimized for manual coding — it's optimized for AI-assisted development Target User Frame is for developers who do daily development with AI coding tools, working terminal-focused. If you find yourself spending most of your time in Claude Code or Codex CLI — and just need a better way to manage your projects and preserve context — Frame is for you. Check out the GitHub repository to get started. ### Context Preservation — Stop Losing Decisions Between AI Sessions Source: https://frame.cool/blog/context-preservation Published: 2026-01-26 Updated: 2026-09-30 The Context Problem You've been there: you start a new Claude Code session, and you have to re-explain the project architecture, the decisions you made yesterday, and the task you were working on. As projects grow, this problem gets worse. Decisions are forgotten. Tasks slip through the cracks. You end up re-explaining the same things over and over. The AI has no memory of what happened in previous sessions. Frame's Approach Frame combines project-wide records with the history of each feature. Project instructions guide the agent to the relevant files; the spec workflow adds intent, implementation decisions and outcomes as work progresses. 1. STRUCTURE.json — The Module Map A machine-readable map of your codebase: which modules exist, what they export, what they depend on. The AI knows where everything is without scanning the entire project. { "modules": { "main/tasksManager": { "path": "src/main/tasksManager.js", "purpose": "Task CRUD operations", "exports": ["init", "loadTasks", "addTask"], "depends": ["fs", "path", "shared/ipcChannels"] } } } This updates automatically via a pre-commit hook — only changed files are parsed, not the entire project. 2. PROJECT_NOTES.md — Decision Log This is where decisions and important conversations are captured — as they happen, not as summaries after the fact. "Don't write a summary — add the conversation as is, with its context. The user's words, the reasoning, the alternatives considered." Record the reasoning, alternatives and relevant user context while a decision is fresh. Project notes complement the feature-specific history in specs and outcomes. 3. tasks.json — Task Tracking Tasks are detected from conversations automatically. When the user says "let's add this feature" or "we'll do this later", the AI recognizes the pattern and offers to add it to the task list. Each task includes the user's original request (verbatim), acceptance criteria, and technical notes — so a future session has full context on what needs to be done. Design Principles Several key principles shaped this system: No "End Session" button — context capture should be organic, not forced User decides importance — the AI suggests, but never auto-saves notes without asking Not summaries, but conversations — context must be preserved as-is Don't spam — not every small change deserves a note. Typo fixes, simple corrections — skip those How It Works in Practice When you start a new session with Claude Code in a Frame project, the AI reads AGENTS.md which tells it to check these three files. Those instructions direct it to: The recorded project structure and module dependencies Recorded decisions and their reasoning Pending tasks and their context The next session has a durable starting point. It should still verify the files against the current code and record any new decisions. This approach works with any AI coding tool — Claude Code loads .claude/rules/frame.md natively, and Codex CLI gets the context injected via a wrapper script. Same system, multiple tools. Where spec-driven development fits Project files describe the shared context. A feature’s spec.md, plan.md, tasks.md and outcome.md explain how a particular change came about. Keeping both lets a future session connect a rule to the implementation that introduced it. For a concrete example, follow an email-reminder feature from spec to reusable context.