@onepointfour-packs/flaredeck-agent

Runs a FlareDeck agent on your own machine. It watches the board for work assigned to it, picks each card up, does it in a checkout of its own, reports back on the card, and asks a person when it genuinely needs one.

You need a FlareDeck workspace and an agent account in it (Users → Add Agent). The agent works as that account: its comments, its branches and its pull requests are its own, and you can see everything it did on the card.

Install

npm install -g @anthropic-ai/claude-code @onepointfour-packs/flaredeck-agent

Node 20 or newer. The Claude CLI is what the agent runs on, and it carries its own login — a Claude subscription rather than metered API billing, which matters when an agent runs for hours.

Start

cd /path/to/your/repo
flaredeck-agent login     # once per machine — asks four short questions
flaredeck-agent           # run it; leave it in tmux or a service

login asks which FlareDeck account this machine acts as, authorises GitHub so it can publish branches, works out which repositories it may touch, and offers to set an OpenRouter key for the command guard. It detects an SSH session and gives you a code to paste instead of opening a browser, so a headless box is fine.

What it does with a card

1. Works out where the work belongs. A board can name a repository per component and a branch per environment; the card's own fields then say which repository and which branch. Where a card says nothing, the agent reads it and works it out, and asks a person rather than guessing between several.
2. Takes a checkout of its own. A git worktree per card, on its own branch, cut from the branch that card's environment means. Two agents never share a working tree.
3. Does the work and reports on the card. What it found, what it changed, what it could not do. The account that comments is the account you created.
4. Publishes through tools, never the shell. push_branch pushes the branch this card made and nothing else; open_pull_request targets the branch the board declared.
5. Hands the checkout back when the card is finished and nothing is left on it.

Where you point it

Start it in a repository and it works that repository. Start it in a folder of repositories and it works all of them, choosing per card — login shows you what it found and you tick which ones it may touch. There is no list to maintain: the folder is the declaration.

What it will not do

These are enforced, not asked for in a prompt:

• It cannot push from the shell. origin is fetch-only inside each card's worktree, so git push fails however it is spelled. Publishing goes through the tools, which can only publish that card's own branch.
• It cannot write outside its own checkout. It may read the neighbouring repositories — that is often how a change is understood — but editing them is refused.
• It will not run an irreversible command. With an OpenRouter key it judges each risky command and refuses what cannot be undone; without one, every risky command stops and asks a person. The guard is never off.
• It will not quietly guess. A card whose repository or branch it cannot establish goes to a person, with what is missing, rather than landing somewhere plausible.

None of this is a substitute for branch protection on your remote. It is the door, not the fence.

Asking a person

When an agent genuinely needs something only a person has — an access it does not hold, a decision about what the product should do, permission for something irreversible — it flags the card and the people who can answer are notified, on their phone if they have the app. The ask arrives as one short question with the answers as buttons, so it can be answered in a tap.

Before that happens the harness checks whether the agent could have finished the job itself, and refuses to interrupt anyone over work it was capable of doing.

Engines

Claude by default. flaredeck-agent --agy runs the same harness on Gemini through Google's Antigravity SDK — same tools, same guards, same reporting, so you can compare them on the same board. The Python sidecar it needs is installed on first use.

Commands

| | | | --- | --- | | flaredeck-agent | Run, and keep running | | flaredeck-agent login | Set this machine up | | flaredeck-agent whoami | Which account, which repositories, what is switched on | | flaredeck-agent run "<task>" | One task, right now, without a card | | flaredeck-agent approvals | Answer what your agents are waiting on | | flaredeck-agent providers | Keys for the optional small models | | flaredeck-agent secret | Store a credential the agent may use but never see |

Where things are kept

~/.config/flaredeck-agent/ — one file per machine for logins and keys, one per workspace for what that agent works on. Nothing is stored in your repository, and no credential is written into a config you might copy to another box.