termdeck
Reference
Settings reference
Everything with an exact name: variables, paths, service names, URLs, routes, shortcuts.
Browser data controls
Deletes the cached shell, stored transcript copies, browser preferences, and each chat's remembered permission mode, then reloads. It leaves the login, push subscription, unsent drafts, and each chat's prompt history in place.
Signs this browser out and removes what it kept for your account: stored transcript copies, the chat list, unsent drafts, prompt history, and this browser's push subscription. Only the color theme stays. Changing your password signs out every other browser and stops their notifications.
Agent environment variables
Set these in ~/.termdeck/agent.env on macOS and Linux, and restart the agent. On Windows the equivalent file is %USERPROFILE%\.termdeck\agent.env.cmd using set NAME=value lines.
The machine token, starting with agt_. Written by the installer. Regenerate it from the machine's page in Settings if it is ever exposed.
Where the agent dials. Written by the installer as https://termdeck.io.
Moves the agent directory, token file, and log somewhere else. Set it before installing; the installer records it in agent.env. macOS and Linux only: on Windows the agent always uses %USERPROFILE%\.termdeck.
Use this exact Claude Code binary rather than looking it up on the path.
Same, for Codex.
Same, for Grok.
Set to off and this machine refuses Full access on every engine, whatever the browser asks for. A chat in Full access fails to start with a message saying so; every other mode works as before. See Turning Full access off.
Set to 1 and this machine refuses every change from Extensions: its MCP servers, plugins and skills can be read and checked, but not switched, and the MCP panel in a chat cannot turn a server on or off. See When the switches are locked.
How long a Claude, Codex or Grok run keeps going with nobody attached before it is stopped. The same limit applies to a Claude process kept alive for your background shells. Raise it if you routinely disconnect for longer than four minutes mid run.
Lets an agent started from outside its install folder connect with the installed agent's own token. Without it that copy refuses, because only one agent per token can be connected and the installed one would be turned away while the copy runs.
Skips the installer's read the source prompt. Used by the repair script for unattended runs.
Engine environment variables
These belong to the coding CLIs. Termdeck follows them rather than defining them, so a machine with a relocated config directory works without extra configuration.
| Variable | Effect |
|---|---|
CLAUDE_CONFIG_DIR | Where Claude Code keeps its configuration, projects, and file history. Defaults to ~/.claude. |
CODEX_HOME | Where Codex keeps its configuration and session rollouts. Defaults to ~/.codex. |
GROK_HOME | Where Grok keeps its configuration and credentials. Defaults to ~/.grok. |
CLAUDE_CODE_ENABLE_TODO_TOOLS | Whether Claude keeps a task checklist while it works. Claude Code turns it off for current models by default; Termdeck turns it back on for the Claude chats it runs, so the checklist shows in the transcript. Set it to 0 in the agent's environment to leave it off. |
File locations
| Path | Holds |
|---|---|
~/.termdeck/agent/ | The agent and its two dependencies. |
~/.termdeck/agent.env | Token and master URL, mode 600. |
~/.termdeck/logs/agent.log | The agent's activity log. |
~/.termdeck/logs/agent-crash.log | Windows only. Crashes that happen before the agent's own handler runs. |
~/.termdeck/persistence.json | How the agent was registered, so the dashboard can warn about fragile installs. |
~/.termdeck/.endpoints.json | The addresses the agent can connect through (termdeck.io and the fallback edge.termdeck.io) and the one in use. Rebuilt if deleted. |
~/.termdeck/session-index.json | The machine's chat list (sizes, times, titles, folders), so a reconnect lists chats without rereading transcripts. Rebuilt if deleted. |
~/.termdeck/uploads/<chat>/ | Files attached from the browser, mode 600, swept after a week without use. |
~/.claude/projects/<slug>/<id>.jsonl | Claude Code session transcripts. |
~/.claude/file-history/<id>/ | Claude Code checkpoint snapshots, used by Restore files. |
$CODEX_HOME/sessions/ | Codex session rollouts. |
$CODEX_HOME/config.toml | Codex configuration, including MCP servers, plugins, and the skills turned off in Extensions. |
~/.claude.json | Claude configuration, including MCP servers and which ones are off in each project. |
<project>/.mcp.json | Project scoped MCP servers. |
~/.claude/settings.json | Claude settings. A skill turned off in Extensions is listed under skillOverrides. |
<project>/.claude/settings.local.json | Which .mcp.json servers you approved or turned off in that project. |
<project>/CLAUDE.md or AGENTS.md | The project instruction file Termdeck can edit. |
Service names
| Platform | Registered as | Managed with |
|---|---|---|
| Linux | termdeck-agent, a systemd user unit | systemctl --user status termdeck-agent |
| macOS | io.termdeck.agent, a launch agent | launchctl list | grep termdeck |
| Windows | TermdeckAgent, a scheduled task | Get-ScheduledTask -TaskName TermdeckAgent |
| Fallback | A @reboot cron entry | crontab -l |
URLs
| URL | Purpose |
|---|---|
/install.sh, /install.ps1 | The installer. Needs TERMDECK_AGENT_TOKEN in the environment. |
/uninstall.sh, /uninstall.ps1 | Stop the service and remove the agent. |
/heal.sh, /heal.ps1 | Uninstall and reinstall, reusing the token on the machine. |
/download/agent/manifest.json | The current agent file list. |
/download/agent/<file> | Any agent file, readable without an account. |
/VERSION | A quick reachability check from a machine. |
/llms.txt | An index of every page on this site for AI agents, linking each page's Markdown version. |
/llms-full.txt | Every page on this site as Markdown, in one file. |
Any page plus .md | That page as Markdown, without the site header and footer. For example /docs/install.md. The home page is /index.md. |
App routes
Every one of these is linkable and survives a reload.
| Route | Opens |
|---|---|
/dashboard | The app, on the fleet board. |
#/new | The new chat page, remembering the machine, folder, and engine you picked. |
#/<session id> | One chat. An eight character prefix is enough when no other chat starts with the same characters; Codex chats use the full id, since two started in the same second share their first eight. |
#/approvals | The approval inbox. |
#/terminals | Terminals: chats in tiled panes, laid out like tmux. |
/settings | The grouped settings list on a phone, and General on a wider screen. |
/settings/<section> | A settings section directly, for example /settings/approvals or /settings/data. The old /settings/advanced still opens Data controls. /settings/profile is your profile and activity, /settings/shortcuts the keyboard shortcuts. |
/settings/security | Security & login: your password, and the browsers signed in to your account. |
/settings/security?view=sessions | The Active sessions list, where you log a browser out. |
/settings/usage | Usage, on Overview. Add ?tab=analytics for the cost and token report. The old /dashboard#/usage forwards to Analytics. |
/settings/archived | Archived chats. The old /dashboard#/archive forwards here. |
/settings/billing | Your plan, promo codes, payment history and cancelling. ?plan=starter or ?plan=pro starts that plan's checkout for an account with no plan, and ?code= opens the promo code window with the code filled in. Older links to /settings/account with either one still arrive here. |
/settings/billing?view=plans | The plans side by side, to subscribe or switch. |
/settings/billing?view=transactions | Every payment on the account, ten at a time. |
?view=<name> and ?tab=<name> | On a settings section, a page inside it and a tab on it. Back leaves a page inside a section; a tab is not a step in your history. |
Keyboard shortcuts
| Keys | Action |
|---|---|
| Ctrl K | Open the command palette. |
| Ctrl B | Collapse the sidebar, or open the drawer on a phone. |
| Ctrl Shift F | Open the project file explorer. |
| Ctrl R | Search prompt history, with the composer focused. |
| Alt 1 to 9 | Jump to a pinned tab, or go to that pane on the Terminals page. |
| Esc | Close the open menu, sheet, or dialog. |
| Every shortcut, including the composer and Approvals page keys, is listed under Keyboard shortcuts. | |
Slash commands
Typing / in the composer opens a palette. Every row carries the command's description and its arguments, read off disk, so your own commands and skills are described alongside the built ins below, including any this project defines.
| Command | Effect | Engines |
|---|---|---|
/compact | Summarise the conversation so far and continue with the shorter version. | Claude, Codex, Grok |
/context | Report context usage. | Claude, Grok |
/model | Change model from the composer. | Claude, Grok |
/session-info | Session details. | Grok |
Codex has none of its own. Its palette lists the skills installed for the chat, and picking one writes it into the composer as text for the model rather than running a command.
These are handled by Termdeck itself rather than sent to the engine, so they work on all three:
| Input | Effect |
|---|---|
/clear | Stops and archives this chat, then starts a new one with the same settings. |
# followed by text | Appends that line to the project instruction file. Never destructive, so it needs no confirmation. |
| Recap, from a chat's menu | A factual summary of what the chat did, derived from its own transcript rather than generated. |
Naming rules
- Machine names are lowercase letters, digits, and dashes, up to 32 characters. The name appears in every route addressing that machine.
- Display names are free text and only affect what you see.
- Machine tokens start with
agt_and are stored hashed on the server.
In Settings, switches and menus show nothing when they save, and a notice at the bottom right when they cannot, with the control back on the value that is really stored. That includes the account reasoning switch on General, whose notice names it, because the server can answer after you have moved to another section. Machine edits retain your entered values when a save fails. Extension connection checks announce their pending and completed status beside Recheck.
Settings opens with focus on the page heading. Select the search field when you want to search. Back to app returns to the workspace view you left.