# Local State: What remits-cli Knows and Where > A `remits-cli` skill reference. **Load this when** a question is about repo discovery, authentication state, what a command actually sent or received, or where a large tool response went. > > The table of contents below carries **real line numbers** (`- L84 Some Heading`), resolved when > this file is installed, so they are never stale. Read the head, pick your sections, and offset-read > only those. The entry text is the heading verbatim, so it also greps. ## Table of Contents - [Required Local Index Reads](#required-local-index-reads) - [Big Picture: How remits-cli State Is Organized](#big-picture-how-remits-cli-state-is-organized) - [Account Repository Index](#account-repository-index) - [Local State Files](#local-state-files) ## Required Local Index Reads These files are decision inputs. Read them when the related decision depends on them. - `~/.remits-cli/account-repos.json` - The inventory of every local Remits repo. Account repos are keyed by numeric account id. - It also contains the reserved **`platform`** entry: the local clone of the core Remits platform repo (`type:'PLATFORM_REPO'`, with its `directory` path). `remits-cli` clones it on first authenticated run if it is missing (default `~/remits`, override with `REMITS_PLATFORM_DIR`). Read this entry when you need to analyze a back-stage seam or open a platform-fix PR. - Read before choosing a repo outside the current working directory. - Read when a support ticket references an account and you need to locate the correct local repo. - Read before concluding that a repo does not exist locally. - `~/.remits-cli/config.json` - Read when service lifecycle, dashboard, or preferred-agent behavior matters. - `~/.remits-cli/service-state.json` - Read when the local control center URL, current dashboard port, repo-scan summary, or websocket status matters. - Read when the user asks whether the remits-cli service is running or where to open the browser view. - `~/.remits-cli/agents.json` - The agent sessions registered from THIS machine, each with the process it is anchored to. - Read when `remits-cli agent work` says no agent is registered, or when several agents are registered and a command needs `--agent-id`. - `~/.remits-cli/activity.log` - Read when diagnosing service lifecycle, websocket, agent registration, or ticket-routing failures. - `~/.remits-cli/sessions.json` - Read when authentication state, active accounts, base URLs, websocket topics, or per-account data mode matters. - `./.remits-cli/workspace` - The staging lane selector for this checkout. It is not the local filesystem session namespace. - `./.remits-cli/actors//current-session.txt` - Read before opening repo-local session logs so you know which actor-scoped session file is current. - `./.remits-cli/actors//sessions/.jsonl` - Read when the question is about what HTTP calls this local actor recently made through remits-cli. Request entries and ordinary response bodies contain bounded summaries/hashes by default, not raw nested payloads. - `./.remits-cli/actors//tool-responses/.json` - Read when `remits-cli tool` says the full payload was stored externally. - `./.remits-cli/shared/tools/tools.json` - Read when the question is about available tool names, cached schemas, or why a tool invocation shape may be invalid. - `./.remits-cli/actors//verification/` - Local mirror and active pointers for verification envelopes for this actor. - `account-info.json` - Read in the target repo before making component changes or assuming account ownership. - `account-configurations.json` - Read only when account configuration values matter. It is generated separately because configuration maps can be large and `account-info.json` deliberately omits them. Do not rely on memory for these indexes. Read the file that governs the decision you are making. ## Big Picture: How remits-cli State Is Organized Think about remits-cli as two cooperating layers: 1. **Global machine state** in `~/.remits-cli/` - This is the cross-repo control plane. - It answers questions like: - which accounts are authenticated - which repos exist locally - whether the background service is running - where the control center lives - which agent sessions are registered from this machine 2. **Per-repo state** in `./.remits-cli/` - This is the request/response and cache layer for one specific working tree. - It answers questions like: - which local actor/session log is current - which `/cli/*` calls were made from this repo - where a large tool response was written - which tool schemas were most recently cached here Per-repo state has two independent namespaces: - **Workspace** (`--workspace`, `REMITS_WORKSPACE`, `.remits-cli/workspace`) chooses the server-side Redis staging lane. It changes what staged entries a run resolves. - **Local actor** (`--local-agent`, `REMITS_AGENT_ID`, generated fallback) chooses the local filesystem namespace under `.remits-cli/actors//`. It changes where session logs, tool responses, verification mirrors, and diagnostics are written. Run `remits-cli doctor local-state` to print the active actor, state directory, workspace source, foreign actors, git-tracked `.remits-cli` files, legacy flat state, and large/suspicious logs. Tool response files under `./.remits-cli/actors//tool-responses/` are the full CLI results. The CLI may print a size/hash hint for large files so you can inspect them selectively with `jq`, `rg`, or byte-range reads, but it does not truncate the local JSON file. Legacy flat `./.remits-cli/tool-responses/` files remain readable as fallback; `doctor local-state` labels them as legacy state. Do not confuse this with the in-platform OpenRouter client, which can offload large tool results inside the model conversation and inject a read-back tool for the AI. When a user asks an indirect question, map it to the right layer first: - "Why did this ticket open in the wrong repo?" → start in global state. - "What exact payload did this tool call send?" → start in per-repo state. - "Why is the dashboard showing stale repos?" → start in `service-state.json` and `account-repos.json`. - "Why is the browser page not showing websocket activity?" → start in `service-state.json` and `activity.log`. - "Why is my agent not getting tickets?" → start in `agents.json`, then `remits-cli agent list`. Agents should use this mental model before guessing. ## Account Repository Index The account repository index file is located at: `{{ACCOUNT_REPO_INDEX_PATH}}` This JSON file is automatically maintained by `remits-cli` and tracks all known Remits account repositories on this machine. It is updated whenever any `remits-cli` command runs from an account repo directory. The file maps account IDs to their metadata: ```json { "37": { "accountId": 37, "name": "Acme Corp", "directory": "/Users/you/Projects/remits-acme-corp", "updatedAt": "2026-03-23T12:00:00.000Z" } } ``` **Use this index to:** - Discover which account repos exist on this machine when working from a different directory - Navigate to another account's repo to read its `account-info.json` and component source - Resolve account names and IDs without making remote API calls - Support cross-account workflows where an agent in one repo needs context from another If the index file doesn't exist yet, run any `remits-cli` command from an account repo to bootstrap it. ## Local State Files **Global** (`~/.remits-cli/`): - `sessions.json` - Source of truth for authenticated account sessions, keyed by `accountId + dataMode + baseUrl` so the same account can hold separate sessions for different environments (e.g., localhost vs production). - Each entry contains auth token, user info, websocket topic, data mode, base URL, and timestamp. - Read this when a question involves auth, account selection, websocket topic coverage, or which session a command should resolve. - `config.json` - Global CLI preferences. - Currently most important for preferred agent selection, but treat it as the general machine-level config file. - `service-state.json` - Runtime snapshot for the currently running remits-cli service. - Includes dashboard URL, chosen port, repo-discovery summary, and websocket connection state. - This is the first file to read when the user asks "is remits-cli running?", "what port is the dashboard on?", or "why isn't the browser page showing my connections?" - `account-repos.json` - Index of all known account repositories on this machine. - Built from `account-info.json` discovery plus best-effort updates when commands run inside an account repo. - This is the repo-resolution file. Read it before deciding that a repo is unavailable locally. - `listener.pid` - PID of the background remits-cli service process. - Use it only to confirm process presence; use `service-state.json` for richer service details. - `agents.json` - The agent sessions registered from this machine, each with the process it is anchored to. - Read this when a command asks for `--agent-id`, or when an agent appears registered locally but is missing from `remits-cli agent list` (that gap IS the "why am I not getting tickets" answer). - `activity.log` - Human-readable chronological event log for service lifecycle, websocket events, agent registration/heartbeat, and ticket routing. - This is usually the best forensic file for "what happened?" questions. **Per-repo** (`./.remits-cli/`): - `workspace` - Staging lane selector for this checkout. Precedence is `--workspace` > `REMITS_WORKSPACE` > `.remits-cli/workspace` > shared default lane. A workspace does not choose local log directories. - `shared/tools/tools.json` - Cached tool definitions for this repo context. - Read this when tool availability or input shape is unclear. - `actors//sessions/.jsonl` - Actor-scoped HTTP request/response log for `/cli/*` calls. - Tokens are redacted. Request payloads are summarized with keys, sizes, hashes, and redaction markers by default; raw nested tool input is not logged unless `REMITS_CLI_UNSAFE_LOG_PAYLOADS=1` was set. - Ordinary response bodies are also summarized so guide syncs, verification packets, and other large responses do not bloat the session log. Full `remits-cli tool` results are stored in `actors//tool-responses/.json`. - This is the first file to inspect when the question is "what exactly did remits-cli send or receive from this repo?" - `actors//tool-responses/.json` - Full payload for `remits-cli tool` responses that were too large for the session log. - Prefer this over terminal summaries when investigating tool behavior. - `actors//current-session.txt` - Pointer to the active repo-local session log name. - `actors//verification/` - Local verification envelope mirror and active context pointers for this actor. - Legacy fallbacks: `sessions/`, `tool-responses/`, `verification/`, `tools/`, and `current-session.txt` - New writes do not use these flat paths. Existing files remain readable for compatibility and are reported by `remits-cli doctor local-state`. Reading rules: - Read `actors//current-session.txt` before opening a session log by name. - When a tool call says the response was stored externally, open `actors//tool-responses/.json` instead of inferring from the terminal summary. - Use `remits-cli doctor local-state` first when inheriting a checkout or when more than one actor directory exists. - If a question spans both global and repo-local behavior, inspect both layers and explain which facts came from which layer.