termdeck
Features
MCP and project context
Two things decide what an agent can reach and how well it behaves: the tools it is connected to, and the instructions sitting in the repository. Both are visible and editable from Termdeck.
MCP servers Starter
Model Context Protocol servers are how a coding agent reaches things beyond the filesystem: a database, an issue tracker, a browser, an internal API. They are configured in your CLI, on the machine, and Termdeck shows you what a session actually has.
Open the MCP panel from the transcript header. It lists every server configured for that session, where the configuration came from, and its connection state.
Where the configuration comes from
| Engine | Read from |
|---|---|
| Claude | ~/.claude.json for user level servers, the same file's per project section, and a .mcp.json in the project root. |
| Codex | The mcp_servers sections of $CODEX_HOME/config.toml. |
Termdeck reads these files, it does not rewrite them. Adding or removing a server is still done where you already do it.
Connection state, honestly
The panel distinguishes three answers rather than two:
- Connected or failed, with the reason, when the engine has reported.
- Not reported, when nothing has observed this server yet, for example a session that has never run. This is never painted green.
- As of a time, when the reading is from the last turn. Connection state can only be asked for mid turn, so an idle session shows the last answer with its age attached.
A dead MCP server is one of the more confusing failures to diagnose from a transcript, because the agent simply stops being able to do something it could do yesterday. Seeing it marked failed, with the reason, is most of the diagnosis.
Reconnect and disable
The panel can reconnect a server or disable one. Both need a live turn, since there is no engine running between turns to act on. The buttons disable themselves rather than pretending otherwise.
Secrets never cross the wire. Auth headers, environment values, and credentials embedded in a URL are stripped before the list leaves your machine. All that survives is a flag saying the server uses authentication.
The project instruction file
Most repositories that work well with coding agents have an instruction file at the root: CLAUDE.md or AGENTS.md. It is where you write down the things the agent keeps getting wrong.
Termdeck can read and edit that file for the folder a chat is running in, which makes it the one file you can fix from a phone when an agent is repeatedly doing something you do not want.
Two ways to change it
| Action | Behaviour |
|---|---|
| Edit | Opens the file, you change it, and saving replaces it. Last write wins, and the editor tells you so. |
| Quick add | Start a composer message with # to append one line. Never destructive, which is why it needs no confirmation and no editor. |
Quick add is the one to reach for in the moment. When an agent does something for the third time that you wish it would not, add the line and it applies from the next turn.
Why this file and not the rest
The file dock is deliberately read only: a general purpose editor over someone's whole checkout would mean owning conflict resolution for every file in it. The instruction file is the exception because editing it by hand is its entire purpose, and because the write is tightly bounded. Termdeck names a session and an engine, never a path, and the machine resolves the target itself from that session's own record against a fixed two entry table of filenames.
Writing instructions that help
- Write what is true and non obvious about the project, not what the code already says.
- Record decisions and constraints, especially the ones you have had to repeat.
- Name the commands: how to run tests, how to build, how to lint.
- Leave out live state such as what is currently running or which version is deployed. It goes stale within the hour and will be believed anyway.
A note on hooks
If your CLI settings define a PreToolUse hook, it can block a tool call before Termdeck ever sees it, which reads from the browser as a tool call that simply did not happen. Run checks on the machine card lists any armed hooks so this is visible rather than mysterious. The same page flags a settings file that fails to parse, which the engine ignores silently along with everything configured in it.