8000 GitHub - simon-inkie/inkie-deck: Open source agent-ops platform, extracted from Mission Control. · GitHub
[go: up one dir, main page]

Skip to content
  • About

    Open source agent-ops platform, extracted from Mission Control.

    Resources

    Contributing

    Stars

    0 stars

    Watchers

    0 watching

    Forks

    Repository files navigation

    Inkie Deck

    One inbox for your AI agent team.

    Inkie Deck is a local-first control room for your AI agents. Run Claude Code, Codex and Antigravity side by side, and bring their decisions and actions back to one place, as cards. With the Brain, our open source long-term memory, your agents remember across sessions.

    Deck has no authentication and binds to loopback by default. Keep it local unless you put it behind your own access control, such as a VPN, a restricted tailnet or a reverse proxy with authentication, before anyone else can reach it. See the deployment boundary and Quick install.

    Open source under the Apache-2.0 licence; contributions are welcome.

    Running ten agents at once broke my brain. Every window wants an answer: approve this, check that, which worktree is it in, is it ready to merge. After three weeks off I came back and could only handle two. So I built one place where the agents bring me the decisions, and they keep the noise. That place is Deck.

    Needs you page listing overdue and upcoming decisions from agents, with a separate section for blocked work

    Needs you: every question from every agent in one queue, most urgent first.

    Your agents ask. You answer.

    Agents do not need your eyes on every line of reasoning. They need you for the calls only you can make. In Deck, an agent sends a decision card when it needs a choice and an action card when it needs you to do something. You answer the card, the agent carries on, and the whole exchange stays in the thread.

    Unanswered decision card with two options: launch the spring stationery range this week or wait for the gift-box restock. It also offers a free-text reply, Dismiss and Supersede.

    The call is yours: pick an option or write your own answer.

    Agent thread showing an answered decision card, the user's reply and the agent's follow-up

    The decision, your answer and the agent's follow-up, kept together.

    Supported harnesses

    The CLI harnesses verified by the scaffolding and launcher tests in packages/base share one inbox, one Needs you queue and one project board. Available models depend on the harness you use.

    Harness Today
    Claude Code Default for one-command setup: generated persona files, persona checks, live check and inbox delivery.
    Codex Supported: --runtime codex creates the agent with an AGENTS.md and a start-up hook that loads its persona, plus launch, resume and inbox delivery. Live check is opt-in.
    Antigravity (Gemini) Supported: --runtime agy creates the agent with a GEMINI.md built from its persona files, plus launch, resume and inbox delivery. Live check is opt-in.

    Memory hooks and the first-run welcome message are Claude Code only for now. Support for more harnesses is planned.

    Deck contains an experimental Agent Client Protocol (ACP) client exercised with a scripted test adapter only. It is not wired into the running app and does not provide support for real ACP agents yet.

    See the work, not a description of it

    Agents share what they make as inline images and links to files. Open their images, code and notes in the review panel beside the thread.

    A second agent's thread with a launch carousel slide shown inline and links to the kit label and a config file

    A launch carousel arrives as something you can see.

    Review panel with a file list of generated images and code files, and a hero image previewed beside the thread

    Everything an agent produced, open beside the conversation about it.

    A second agent's thread with an inline carousel slide and a link to its launch config, beside the same config open as highlighted JSON

    Code opens with syntax highlighting, right next to the thread.

    Keep the whole team on one board

    Every piece of work sits in one of five stages, each card showing its owner and what it is waiting on. You can see who is stuck without asking anyone.

    Project board with twelve cards across to do, in progress, blocked, in review and done

    Twelve pieces of work, five stages, one glance.

    You can also edit Markdown drafts in the browser, open linked documents in the review panel, and type or dictate replies (optional voice dictation with an API key).

    Not just for code

    Deck runs my own business every day: marketing, customer outreach, support, CRM hygiene and code. Agents on the supported harnesses can bring decisions and actions from that work back to Deck.

    Built in daily use, not in a lab

    Deck began as an internal tool: the team of agents behind it has been running since April 2026, and the app itself, first committed on 3 June 2026, has run my business every day since, growing a piece at a time as the team needed it. This is the open source part of that tool, and I now run on this open source version myself. It looks simple. Underneath it is not, and that is the point: the complexity is the tool's problem, not yours.

    It is built to be built on. Your agents can extend it with you, and a plugin system is planned.

    Give your agents a memory that lasts

    Deck pairs with the Brain, our open source long-term memory for AI coding agents, in use since April 2026:

    • Survives compaction. It captures decisions, debugging state and rejected ideas to disk before compaction wipes them, and brings them back next session.
    • Remembers across sessions. Semantic search over notes, observations and past conversations, so an agent can recall what the team already worked out.
    • One memory per agent, one shared vault. Each agent keeps its own memory on disk, recall can be scoped to it, and a shared knowledge vault holds what the whole team should know.
    • Filesystem-first. Plain files you can read, edit and back up.

    Run scripts/setup.sh --memory to give both starter agents their own observation silo. Observations appear after compaction, and each costs a model call through the signed-in claude CLI. The basic loop does not set up semantic search or a shared vault. For the manual route, see give the agent a memory loop.

    Why I built it

    Run enough agents and you hit what I call agentic cognitive overload: streams of reasoning and queues of approvals, all competing for the same human brain. It is not only a coder's problem. Deck is my answer: work at a normal pace and let the agents bring you only what needs you.

    Watch: Agentic Cognitive Overload: Running 10 AI Agents Broke My Brain

    Watch (5 min): Agentic Cognitive Overload: Running 10 AI Agents Broke My Brain.

    Why "Deck"

    All hands on deck: your whole crew of agents, on one ship. And a deck of cards: they deal you decisions and actions, you play them, and nobody reads every thread. Go and make something good, and take it easy on your head.

    Quick install

    Deck has no authentication; put it behind your own access control before anyone else can reach it.

    Try the demo, no AI CLI needed: from your clone, with Node and pnpm installed:

    pnpm install && pnpm dev

    Open http://localhost:4242 for the interface with throwaway fixture data. See Try it.

    For Quick setup with live agents: Node ^22.13.0 || >=24.0.0, pnpm 10.34.5 via Corepack, and the Claude Code CLI installed and signed in. See prerequisites for system packages.

    Run as your own user, not as root:

    git clone https://github.com/simon-inkie/inkie-deck.git && cd inkie-deck
    scripts/setup.sh

    To opt in to the Brain, run scripts/setup.sh --memory (requires Node 22 or newer and jq).

    On Windows: Follow the WSL2 setup notes first. Keep the clone in your Linux home (for example, ~/inkie-deck), not on C: (/mnt/c).

    Open the URL setup prints in your browser (default: http://127.0.0.1:4242/). If setup stops for first-run prompts, answer them in Deck and run scripts/setup.sh again. Once the assistant starts, its first message asks what you do and what 9B64 you would like help with first. Reply in its thread.

    Full instructions: INSTALL.md. The three manual tiers cover a five-minute sandbox with fixture data, a production install, and live agents in tmux. The rig extracts and runs the covered shell blocks directly from the guide.

    Quick setup starts a Claude Code agent. To add a Codex or Antigravity agent, run create-agent.sh --runtime codex or --runtime agy; see the harness table above. To add another agent, see docs/adding-an-agent.md.

    How this repository got its code

    Deck's application code was copied in from the working platform and cleaned, not reimplemented. That platform is proven and in daily use; rewriting it would throw away everything its testing has established and buy nothing. What got re-authored is only the material that could not be cleaned economically: fixtures, test data and persona files, which encode specifics of one deployment rather than the shape of the product.

    No git history crosses. The leaks are in commit messages, so the extraction copies file contents into fresh commits and the old history stays behind. That is the one part of this with no exceptions.

    Layout

    A pnpm workspace with two packages:

    • packages/base: the agent protocol package (inkie-agents-base). The normative spec of the file-based message protocol (docs/protocol.md), persona-file templates, a fully worked fictional example agent, and the shared multi-agent conventions. Bundled here so Deck's docs and templates travel with it, but independently versioned and kept separable so it can move to its own repository later.
    • packages/deck: the application package (inkie-deck). The React Router web application plus its unit suite (vitest) and browser journeys (Playwright). It implements the packages/base protocol directly; there is deliberately no second implementation anywhere in the repository.

    Contributing

    The contributing rules, the checks a pull request must pass and the Developer Certificate of Origin are in CONTRIBUTING.md. The workflow around them is DEVELOPMENT.md, and it applies to AI coding agents as much as to humans: that is the file AGENTS.md and CLAUDE.md point at, so every runtime reads one set of rules. If you are starting work on an issue, the start-issue skill creates the branch and the SPEC skeleton for you.

    The rules the machines enforce

    • packages/base never imports from packages/deck, and packages/deck reaches base only through its published entry points. Enforced by dependency-cruiser (pnpm check:boundaries).
    • No internal material (names, hosts, paths, tickets, addresses) may enter the repository. Enforced by scripts/leak-gate.mjs plus gitleaks in CI. The gate self-tests: node scripts/leak-gate.mjs --self-test proves each rule still fires, so a rule that has quietly stopped matching cannot pass as a clean scan.
    • The LICENSE must name a real copyright holder rather than a placeholder. Enforced by scripts/licence-gate.mjs.

    Development

    Node ^22.13.0 || >=24.0.0, and pnpm. Both current LTS lines, in other words, and not the odd-numbered ones in between: 23 was never an LTS line and is already out of support. pnpm install refuses to run on anything else and tells you so, rather than letting you find out later or not at all.

    Further prerequisites, all easy to miss because every machine that has run this so far already had them:

    • git, and the tree has to be a clone. An unpacked release tarball or a "Download ZIP" will not do. Two suites shell out to git status --porcelain to prove that a test has not written into the repository, and scripts/leak-gate.mjs uses git ls-files as its file-selection rule. With no .git directory the suite reports dozens of failures that have nothing to do with the code.
    • ripgrep (rg), used by check:dashes.
    • python3, if you want your agents to talk to each other. The inbox CLI in packages/base is Python. Nothing in the web application needs it, so Deck runs fine without it and you will not find out you are missing it until an agent tries to reply and cannot. A bare Ubuntu 24.04 image does not have it.
    • xxd, for the inbox suite alone, which compares the bytes of a thread file before and after an in-place status patch. On Ubuntu 24.04 it is its own package rather than part of vim-common, so it is absent by default and the suite stops with xxd: command not found and no other explanation.
    • a UTF-8 locale. Not only for the suite: live delivery decides whether an agent is busy by reading the spinner and counter glyphs in its terminal pane, and in the C locale that classification breaks. Ten of the seventy delivery cases fail there, and at runtime the same break is a message that was never typed into a pane which was ready for it. A container inherits no locale at all, so LANG=C.UTF-8 belongs in any deployment that is not a desktop.

    The test count doubles as a diagnostic here, with git and ripgrep the two that move it: 2023 passing means everything above is present, 2019 means ripgrep is missing, and 1956 means neither ripgrep nor a git repository is. All three are measured in a container on every rig run rather than remembered; the numbers in this paragraph were wrong by twenty for two days before anything asserted them.

    One more thing about those two suites, because it looks like your bug and is not: they report the state of the tree, not the state of your change. They fail on any modification, including the uncommitted edits you are currently testing. So a run against a dirty tree returns dozens of failures that have nothing to do with what you wrote. Commit first, or stash, then run the suite. Two people lost time to this on the same day, each reading it as their own breakage.

    pnpm install
    pnpm typecheck
    pnpm test
    pnpm check:boundaries
    pnpm check:leaks
    pnpm check:licence

    CI runs exactly this list (plus gitleaks), so a green pipeline never claims more than a green local run.

    pnpm typecheck uses the TypeScript native preview (tsgo) after generating Deck's React Router types. The preview can report different diagnostics from tsc. Run pnpm typecheck:tsc to compare or to check on a platform without a native preview binary. CI requires the tsgo check.

    The codes in the comments

    Comments through packages/deck cite short codes that arrived with the code. Each names a rule rather than a ticket, and until now none of them was defined anywhere a reader could find. Defined here, from what they actually guard in this tree rather than from the register they came out of:

    • FND-02, the seam rule. Anything server-only (environment, filesystem, subprocesses) lives in a .server module, and components and routes receive plain data as props or loader data. The .server suffix is what keeps the module out of the client bundle, so a route reaching for node:fs directly is not a style complaint, it is a bundling failure waiting to happen. Half of it is mechanical: packages/deck/test/seam.test.ts walks every file under app/routes/ and fails on a direct filesystem import or a literal inbox path. The rest is convention, which is why the comments keep saying it.
    • FND-03, roots have no defaults. INBOX_ROOT, ATTACHMENTS_ROOT, PROJECTS_ROOT and DATA_ROOT are required, must be absolute, and must exist. Unset, empty or relative is fatal at boot with the variable named, rather than a default that silently writes your messages somewhere you will never look for them.
    • FND-04, write confinement and write shape. An inbox write must resolve inside the configured root AND look like <agent>/inbox/<file>.md, and traversal-shaped agent or participant names are refused before any path is assembled. MC_SANDBOX_ONLY is the same rule's other half: a sandbox configuration may never be pointed at a live agent silo.
    • FND-05, ASCII only, no em-dashes or en-dashes anywhere in the tree. pnpm check:dashes fails on either codepoint, and the leak gate fails on a literal em-dash as well, for a reason beyond house style: U+2014 is a field separator in the message protocol, so a literal one in a file is a latent parsing hazard.
    • VALID-01, the walking-skeleton proof. packages/deck/test/skeleton.test.ts and its three legs: the app boots and renders its shell, the parser round-trips a real fixture byte for byte, and the write guard refuses both a forbidden root and a symlink escape.
    • VALID-02, the four card journeys, one Playwright spec each: a decision card renders with tappable options, tapping one writes the answer, the action queue persists and ages its deadlines, and a composed reply appends to the thread.
    • VALID-03, browser journeys write only into temporary roots. Backstopped rather than promised: assertGitClean in packages/deck/e2e/flows/helpers.ts fails the run and lists the files if a journey dirties anything tracked, which is what stops a suite from quietly editing the committed fixtures it is supposed to be reading.

    Some comments also cite documents (RESEARCH.md, PLAN.md) and ticket ids (TASK-nnn) belonging to the repository this code was extracted from. Those did not cross and are not coming: read them as provenance, not as something to go and open.

    Licence

    Apache-2.0. See LICENSE.

    About

    Open source agent-ops platform, extracted from Mission Control.

    Resources

    Contributing

    Stars

    0 stars

    Watchers

    0 watching

    Forks

    Releases

    Packages

    Contributors

    Languages

    0