{"id":48288091,"url":"https://github.com/fraction12/potato-v3","last_synced_at":"2026-04-04T23:00:04.461Z","repository":{"id":347692888,"uuid":"1194174495","full_name":"fraction12/potato-v3","owner":"fraction12","description":"Terminal cockpit for coding agents. Rust/ratatui.","archived":false,"fork":false,"pushed_at":"2026-03-29T05:19:45.000Z","size":894,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-29T05:26:49.512Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fraction12.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T02:22:43.000Z","updated_at":"2026-03-29T05:19:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fraction12/potato-v3","commit_stats":null,"previous_names":["fraction12/potato-v3"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fraction12/potato-v3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fpotato-v3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fpotato-v3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fpotato-v3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fpotato-v3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fraction12","download_url":"https://codeload.github.com/fraction12/potato-v3/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fpotato-v3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31418285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T23:00:03.100Z","updated_at":"2026-04-04T23:00:04.377Z","avatar_url":"https://github.com/fraction12.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🥔 POTATO\n\n**Personal Orchestration Tool for Agentic Task Operations**\n\n*A terminal cockpit for coding agents.*\n\nPotato runs real agents like Claude Code and Codex in embedded terminal panes, gives them shared coordination tools over MCP, and lets you watch the work happen in one place.\n\n\u003e Potato does **not** replace your agents. It gives them a shared workspace, project context, and a mission control you can actually use.\n\n![Potato demo](docs/assets/potato-demo-live.gif)\n\n## Why Potato?\n\nCoding agents are already good in isolation. The problem starts the moment you want them to work **together**.\n\nWithout Potato, multi-agent work usually means:\n- too many terminals,\n- too much copy-pasted context,\n- no shared task state,\n- no clean way to see who is doing what,\n- and far too much of *you* acting as the router.\n\nPotato turns that mess into a single project cockpit:\n- launch agents side by side,\n- assign roles,\n- let them coordinate through MCP,\n- keep project context and task visibility in one place,\n- and stay in the loop without micromanaging every turn.\n\n[![Rust](https://img.shields.io/badge/Rust-1.94+-orange?logo=rust)](https://www.rust-lang.org/)\n[![Tests](https://img.shields.io/badge/tests-784_passing-brightgreen)](#development)\n[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n---\n\n## What Potato Is\n\nIf Claude Code is excellent in one terminal, Potato is what happens when you want:\n\n- an **architect** and an **implementer** side by side,\n- a shared **task board** instead of copy-pasting context,\n- project-aware **roles**, **messages**, and **shared context**,\n- and a TUI that shows what your agents are actually doing.\n\nPotato is built in Rust with [ratatui](https://github.com/ratatui/ratatui). It embeds real PTY sessions, tails native agent logs for observability, and wires sessions together through a built-in MCP server.\n\n## What It Does Today\n\n### Real embedded agent terminals\n- Launch Claude Code, Codex, or a generic CLI agent in actual PTYs\n- Keep the native agent feel instead of simulating turns in a fake chat UI\n- Support side-by-side panes for concurrent work\n- Preserve terminal-local scrollback inside each pane\n\n### Coordination via MCP\n- Potato exposes MCP tools to running agents\n- Agents can message each other, claim/release tasks, inspect partner status, and read/write shared context\n- Coordination is project-local and routed through Potato instead of brittle prompt hacks\n\n### A cockpit instead of a pile of terminals\n- **Dashboard-first launch flow**\n- **Role definition** before starting a run\n- **Team / Tasks / Context** right rail during a session\n- **Git panel** on the left for project awareness\n- **Settings** and **Integrations** panels in-app\n\n### Truth-first observability\n- Claude and Codex remain the source of truth for their own session identity and usage\n- Potato reads native logs instead of inventing synthetic state\n- Metrics, tool activity, and session context stay tied to what the agent actually did\n\n### Project-aware workflow\n- Reads OpenSpec task data from `openspec/changes/*/tasks.md` (markdown checkboxes) via the official [OpenSpec CLI](https://github.com/openspec-ai/openspec)\n- Falls back gracefully when OpenSpec is absent\n- Stores project-local coordination state under `.potato/`\n\n---\n\n## Quick Start\n\n### Requirements\n- Rust 1.94+\n- At least one installed agent CLI:\n  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\n  - [Codex](https://github.com/openai/codex)\n  - or another terminal agent via the generic adapter\n\n### Build\n\n```bash\ngit clone https://github.com/fraction12/potato-v3.git\ncd potato-v3\ncargo build --release\n```\n\n### Run\n\nLaunch Potato from the project you want your agents to work on:\n\n```bash\ncd ~/your-project\n/path/to/potato-v3/target/release/potato\n```\n\nOr install it somewhere on your `PATH`:\n\n```bash\ncp target/release/potato ~/.local/bin/potato\ncd ~/your-project\npotato\n```\n\n---\n\n## How It Works\n\n```text\n┌──────────────────────────────────────────────────────┐\n│                      Potato                          │\n│                                                      │\n│  ┌──────────────┐              ┌──────────────┐      │\n│  │ Claude Code  │◄── MCP ────► │    Codex     │      │\n│  │ Architect    │   tools      │ Implementer  │      │\n│  └──────┬───────┘              └──────┬───────┘      │\n│         │                             │              │\n│         └──────────┐     ┌────────────┘              │\n│                    ▼     ▼                           │\n│               shared state                           │\n│          roles · tasks · messages · context          │\n│                                                      │\n└──────────────────────────────────────────────────────┘\n```\n\nPotato launches the agents, manages the panes, hosts the MCP bridge, and keeps the shared coordination state for the current project.\n\n## Built-in Coordination Tools\n\n| Tool | Purpose |\n|------|---------|\n| `potato_send_message` | Send a message to another running agent |\n| `potato_get_messages` | Read queued messages |\n| `potato_get_partner_status` | Inspect what another agent is doing |\n| `potato_claim_task` | Claim a task |\n| `potato_release_task` | Release a task |\n| `potato_shared_context` | Read/write shared project context |\n| `potato_get_role` | See current role assignments |\n| `potato_list_tasks` | Read actionable tasks from OpenSpec when available |\n\n---\n\n## The UI\n\n```text\n┌──────────────┬───────────────────────────────┬──────────────┐\n│ Git / nav    │ real embedded terminal pane   │ Team         │\n│ project info │ active agent session          │ Tasks        │\n│              │                               │ Context      │\n│              ├───────────────────────────────┤ Metrics      │\n│              │ shared input / command bar    │              │\n├──────────────┴───────────────────────────────┴──────────────┤\n│ status bar                                                     │\n└────────────────────────────────────────────────────────────────┘\n```\n\n### Dashboard\nBefore you start a session, Potato gives you a dashboard with:\n- **Roast Potato** — launch the current setup\n- **Define Roles** — set role names/prompts for the run\n- **Integrations** — Git summary, OpenSpec status, and MCP integration info\n- **Settings** — runtime, paths, keybinds, permissions, and coordination info\n\n### Session view\nDuring a run, Potato focuses on project collaboration:\n- **Left rail:** project/git awareness\n- **Center:** real terminal panes with full PTY passthrough\n- **Right rail:** Team, Tasks, Context, and compact agent metrics\n\n### Keyboard\n- **Tab / Shift+Tab** — cycle focus ring (Agents → Git → Input → Terminal → Sidebar)\n- **F1** — help overlay\n- **F2** — agent picker\n- **F3** — session picker\n- **Ctrl+W** — close active pane\n- **Ctrl+\\\\** — return to dashboard\n- In terminal focus, only Tab and Ctrl+\\\\ are intercepted — everything else passes through to the agent PTY\n\n---\n\n## Supported Agents\n\n| Agent | Status | Notes |\n|-------|--------|-------|\n| Claude Code | Supported | Native session/log observability |\n| Codex | Supported | Native session/log observability |\n| Generic CLI | Experimental | Basic terminal hosting via adapter |\n\n---\n\n## Design Principles\n\n- **Real terminals, not simulated chats**\n- **Agents own truth; Potato owns observability**\n- **MCP for coordination, not custom glue everywhere**\n- **Project-local state beats global mystery state**\n- **Useful before perfect**\n\n---\n\n## Current State\n\nPotato is already useful for real multi-agent work, especially on coding tasks where you want multiple agents in one project with a visible coordination layer.\n\nWhat’s solid:\n- embedded PTY sessions,\n- Claude/Codex support,\n- MCP coordination,\n- project-local state,\n- OpenSpec-aware task surfacing,\n- Git-aware left rail,\n- dashboard/settings flow.\n\nWhat’s still maturing:\n- shared context UX,\n- quick-actions panel,\n- capability-aware behavior when project integrations are absent,\n- packaging/distribution beyond local builds.\n\n---\n\n## Development\n\n```bash\ncargo test          # 784 tests\ncargo build --release\nRUST_LOG=debug cargo run\n```\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003csub\u003eBuilt with [ratatui](https://github.com/ratatui/ratatui), [portable-pty](https://github.com/wez/wezterm/tree/main/pty), [vt100](https://github.com/doy/vt100-rust), and [tui-term](https://github.com/a-kenji/tui-term).\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fpotato-v3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffraction12%2Fpotato-v3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fpotato-v3/lists"}