# DOCS
A card moves on its own once the agent in that terminal reports what it is doing. You do not edit the agent's settings. The agent does, and it tells you which file it changed.
## GETTING STARTED
Install tabsh and start it. It opens the app in your browser, already paired with the daemon on your machine.
$ brew install blaise1030/tap/tabsh $ tabsh # no Homebrew? cargo install --git https://github.com/Blaise1030/tabsh
That process runs until you close its terminal. To keep the daemon running from login, stop it and run brew services start tabsh, then open http://127.0.0.1:7681 once in this browser.
Safari, and every iOS browser, cannot reach the daemon from this site. The daemon serves the app at http://tabsh.localhost:7681, and this site sends Safari there.
> Next, connect an agent so its card moves on its own.
## CONNECT AN AGENT
Open the board (⌘B). The first time, choose Set up with Claude Code. That opens a card and hands the agent the setup guide.
Already past that screen, or you use another agent? In a tabsh terminal, paste this to Claude Code, Codex, Gemini CLI or OpenCode:
> Run `tabsh setup` and follow the guide it prints, so your hooks keep your card on the tabsh board current. Run it inside a tabsh terminal. The hooks look for that terminal's card, and outside tabsh they do nothing.
## HOOKS THE AGENT RUNS
tabsh setup prints the guide, and the agent follows it. It backs up the config file first, then adds the commands below. It keeps every hook you already have. Run the setup again and it updates those tabsh lines instead of adding a second copy.
| When | Command |
|---|---|
| You send a prompt | tabsh status in_progress --hook |
| The agent needs your permission or a reply | tabsh status needs_input --hook --if-not completed |
| The agent's turn ends | tabsh status needs_input --hook --if-not completed --note 'Agent finished its turn' |
| The task is done | tabsh status completed --note '<one line: what it did>' |
The last row is not a hook. The agent adds one rule to the instructions it reads every session, and runs that command itself when it decides the task is done. It never sets another status, and it never archives a card. Archiving stays yours.
--hook prints nothing and always exits 0, including outside a tabsh terminal, so the same lines are safe in every shell. It reads the event's JSON. A message field becomes the card's note. A session_idis how tabsh resumes that conversation after a restart. --if-not completed leaves a finished card where it is when a later hook fires.
Each agent writes those commands into its own file:
| Agent | File | Events |
|---|---|---|
| Claude Code | ~/.claude/settings.json | UserPromptSubmit, Notification, Stop |
| Gemini CLI | ~/.gemini/settings.json | BeforeAgent, Notification, AfterAgent |
| Codex | ~/.codex/config.toml | notify |
| OpenCode | ~/.config/opencode/plugins/tabsh.ts | session started, permission asked, execution ended |
For Claude Code and Gemini CLI those events follow the table above, in order: your prompt, the agent needing you, then the turn ending. Codex has a single notify hook and no event for the moment you send a prompt, so the agent leaves that command out. OpenCode's file is a plugin. Its server never sees the terminal, so the plugin finds the card by the conversation tabsh named. Permission asked uses the note OpenCode needs your permission.
The agent checks its own current docs for those event names, and the commands use the tabsh binary it found. Its report names the path it wrote. If that path is a build folder under target/, the report says so, because the hooks would point at it.
A desktop notification and a chime fire when a hook moves a card to Needs input or Completed and that terminal is not the one on screen.
## WHAT YOU SHOULD SEE
The agent reports back:
- The file it changed, and a
.bakcopy beside it. - Which of those commands it connected, and which its agent has no way to report.
- How to undo it.
While it checks the connection, the card moves to Needs input with the note setup test, then back to In progress. If the card never moves, paste that report back into the same terminal and ask the agent to fix the connection.
## UNDO
Ask the agent to remove the tabsh hooks. Its report names the file. The entries to remove are the ones whose command contains status , --hook and the word tabsh, plus the instruction that marks a card completed. OpenCode's wiring is the one plugin: delete ~/.config/opencode/plugins/tabsh.ts.
~*~ EOF ~*~