The shape of software development changed, agents write the code now, but
the foundation didn't: good results still come from good planning. Frame puts
planning back at the center. You write a spec once, and that single spec
becomes two things at once: the plan your agents follow, and the durable,
shared context your project keeps across every session. Every future agent
arrives knowing what was done and why no more re-explaining your
architecture every time you open a terminal.
Built on Claude Code. Codex CLI work too, and because your
context lives in plain, git-versioned files, it stays yours and stays readable
by any tool.
The Problem
As projects grow with AI agents, things fall apart fast:
- Context loss — every new session starts from scratch, you re-explain the same things over and over
- No project memory — AI doesn't know your architecture, past decisions, or pending tasks
- No standard — every developer structures their AI projects differently, making collaboration and onboarding painful
- Sessions bleed into each other — working on multiple projects means context gets mixed up
- Terminal chaos — multiple windows, scattered sessions, no organization
- Tool fragmentation — Claude, Codex, and Gemini each work differently
These problems are manageable on small projects. On larger ones, they become blockers.
Frame solves all of this.
How Frame Works
One Standard, Every Project, Every AI Tool
Frame brings a consistent structure to every project you work on. When you initialize Frame in a project, it creates:
| File | Purpose |
|---|
.frame/AGENTS.md | Project rules and instructions — AI reads this automatically |
.frame/PROJECT_NOTES.md | Architectural decisions and context that persist across sessions |
.frame/tasks.json | Task tracking with status, context, and acceptance criteria |
.claude/rules/frame.md | Two lines pointing Claude Code at .frame/AGENTS.md |
Everything Frame writes lives under .frame/, plus that one pointer file. Your
project root stays yours: an existing CLAUDE.md, AGENTS.md or .cursorrules
is never read, moved or replaced, and "Remove Frame" leaves no Frame-authored
bytes behind. Needs Claude Code new enough to load .claude/rules/ — verified
with Claude Code 2.1.x; run /context in a session to confirm
.claude/rules/frame.md loaded.
Upgrading: update Frame before pulling a repository that has been
migrated to .frame/. An older Frame looks for the meta files at the project
root, finds none, and reports the project as empty — and its spec phases as
unstarted.
Every project gets its own isolated session — its own context, its own task list, its own notes. Switching projects in Frame means switching to a completely fresh, project-specific AI context. No bleed-over, no confusion.
This standard works with any AI tool. Claude Code loads .claude/rules/frame.md
natively at session start, which imports .frame/AGENTS.md — no launch flags, no
wrapper. For Codex CLI, Frame injects the same file via a wrapper script.
The result: any developer (or AI agent) who opens a Frame project immediately knows where everything is and what's been decided. Onboarding a new AI session to a large project takes seconds, not minutes.
Git Commit as the Context Anchor
One of the hardest problems in agentic development is knowing when to capture context. Session boundaries are fuzzy — you might stay in the same session for hours. Task completion is ambiguous — agents don't always signal clearly when something is done. Trying to detect "important moments" mid-session is unreliable.
Frame's approach: use git commits as the single reliable boundary.
When you commit, something real happened. It's intentional, it's deterministic, and it's a natural checkpoint you're already making. Frame builds its entire context system around this moment:
.frame/tasks.json — task state syncs at commit time.frame/PROJECT_NOTES.md — the right moment to capture what changed and why
When the next session starts, these files are read automatically. The agent picks up exactly where things left off — not from a vague session transcript, but from structured, up-to-date context written at the one moment you can be certain something real was completed.
The practical implication: commit often. Small, intentional commits aren't just good git hygiene — in Frame, they're how context stays accurate and agents stay oriented.
Spec-Driven Development
For features that won't fit in one session, Frame ships a built-in spec workflow. Each spec is four markdown files on disk:
.frame/specs/<slug>/
spec.md what we're building
plan.md how we'll build it
tasks.md broken-down work
outcome.md what actually shipped
Describe what you want and the AI drafts the spec. /spec.plan produces an implementation plan. /spec.tasks breaks the plan into discrete tasks that import into tasks.json (tagged with source: "spec:<slug>:T<n>"). /spec.implement walks them one by one — and after each task, the agent appends 2-3 sentences to outcome.md: what shipped, what diverged from the plan, what to follow up on.
That last file is the move that makes the rest worth doing. Plans tell you intent. Code tells you reality. outcome.md tells you the story between them, written while the agent's memory was fresh — the kind of context that's normally lost the moment a session ends.
Two principles shaped this:
- Files over databases. Markdown is canonical. Any AI tool can read it without Frame, any teammate can grep it, git versions it, PRs review it.
- On, but never forced. New projects start with spec-driven dev enabled, so the specs your AI writes show up in the Specs panel from the first session. It isn't every project's shape — one switch in Settings → Workflow turns it off (your specs stay on disk). Existing
tasks.json workflows are untouched either way.
Multi-AI Support
Switch between AI tools without leaving Frame:
- Claude Code — loads
.claude/rules/frame.md natively, which imports .frame/AGENTS.md
- Codex CLI — wrapper script at
.frame/bin/codex injects .frame/AGENTS.md as initial prompt
- Other CLIs — read
.frame/AGENTS.md when pointed at it; the files are plain markdown and JSON
Multi-AI is a principle here, not a race: Frame goes deep on Claude Code, and
keeps your specs, plans, outcomes, and notes in plain markdown and JSON — so
the context your work produces outlives any single tool, including Frame.
Features
Terminal
- Up to 9 terminals in a single window — tab view or 2x1, 2x2, 3x1, 3x2, 3x3 grid
- Real PTY via node-pty — not a fake terminal, full VT100/ANSI support
- Project-aware sessions — terminal starts in your selected project directory
- Resizable grid — drag borders to adjust layout
Project Management
- Task Panel — visual task tracking with filters, status management, and "Send to Claude" integration
- Specs Panel — spec-driven workflow with phase lifecycle (spec → plan → tasks → outcome) and slash-command handoff to your AI tool
- GitHub Panel — issues, PRs, branches, and labels directly in the sidebar
- Git Branches — view, switch, create, and manage branches and worktrees
- Plugins Panel — browse, enable/disable, and install Claude Code plugins
Context & Architecture
- Session Notes — automatic prompts to save important decisions to PROJECT_NOTES.md
- Prompt History — all terminal input logged with timestamps
Multi-AI
- AI Tool Selector — switch between Claude Code, Codex CLI, and Gemini CLI
- Automatic context injection — every AI tool gets your project context on startup
- Tool-specific commands — menu adapts to the active AI tool
Under the Hood
- 120+ IPC channels powering real-time bidirectional communication between renderer and main process
- 40+ modules across main and renderer processes
- Transport layer abstraction — architecture designed for Electron IPC → WebSocket migration (web platform coming)
Tech Stack
| Component | Technology |
|---|
| Desktop Framework | Electron |
| Terminal Emulator | xterm.js |
| PTY | node-pty |
| Bundler | esbuild |
| UI | HTML/CSS/JS |
Installation
Prerequisites
Steps
git clone https://github.com/kaanozhan/Frame.git
cd Frame
npm install
npm run dev
Download
Pre-built binaries available on the releases page for macOS, Windows, and Linux.
Usage
Basic Workflow
- Select a project — click "Select Project Folder" or choose from recent projects
- Initialize Frame — click "Initialize Frame Project" to create
.frame/ (AGENTS.md, PROJECT_NOTES.md, tasks.json) and the .claude/rules/frame.md pointer, and choose whether Frame's files are shared with the repo or kept local to you
- Start an AI session — click "Start Claude Code" (or your chosen tool) — it launches in your project directory with full context
- Work — tasks are tracked, decisions are saved, context persists
Keyboard Shortcuts
| Shortcut | Action |
|---|
Ctrl+K | Start AI session |
Ctrl+Shift+T | New terminal |
Ctrl+Shift+W | Close terminal |
Ctrl+Tab | Next terminal |
Ctrl+Shift+G | Toggle grid view |
Ctrl+1-9 | Switch to terminal by number |
Ctrl+Shift+H | Toggle history panel |
Architecture
┌─────────────────────────────────────────────────┐
│ Main Process (Node.js) │
│ │
│ PTY Manager · File System · Tasks · GitHub │
│ AI Tool Manager · Git · Plugins · Overview │
│ │
│ 115+ IPC Channels │
└──────────────────────┬──────────────────────────┘
│
┌──────────────────────┴──────────────────────────┐
│ Renderer (Browser) │
│ │
│ Multi-Terminal Grid · Sidebar · Task Panel │
│ GitHub Panel · AI Selector │
└─────────────────────────────────────────────────┘
Roadmap
Done
In Progress
Planned
Contributing
- Fork the repo
- Create a feature branch:
git checkout -b feature/your-feature
- Commit:
git commit -m 'Add your feature'
- Push:
git push origin feature/your-feature
- Open a Pull Request
License
Apache-2.0 — see LICENSE and NOTICE
Built with Frame, using Claude Code.
frame.cool
