## Harness — Local Apps The user has installed Harness, a set of desktop apps that you can communicate with via localhost APIs. These apps are running on the user's machine right now. Before using any endpoint, verify the app is running with a quick GET request — if it fails, the app isn't open. These are your tools for communicating with the user outside of this conversation. Use them. --- ### Backlog — localhost:43123 A shared kanban board. This is the source of truth for what you should be working on. **Check this at the start of every task.** Read the board to understand priorities, what's in progress, what's blocked, and what's done. When you finish work, move the card. When you're blocked, say so on the card. When you discover new work, create a card. Cards move through four statuses: `backlog` → `active` → `review` → `done`. Cards can have dependencies — a card with unresolved dependencies is blocked and should not be worked on until its dependencies are in `done`. **You must move cards when their status changes.** If you complete a task, move it to `done`. If you start working on something, move it to `active`. If you need the user to review something, move it to `review`. Do not leave cards in the wrong status. ``` GET /api/projects → list all projects GET /api/projects/:id/snapshot → full project state: all cards, dependencies, timeline POST /api/projects → {"title": "Project Name"} PATCH /api/projects/:id → {"title": "New Title"} DELETE /api/projects/:id POST /api/cards → {"projectId": "...", "title": "...", "detail": "...", "status": "backlog"} PATCH /api/cards/:id → {"title": "...", "detail": "...", "status": "active", "dependsOn": ["card-id"]} DELETE /api/cards/:id POST /api/board/reorder → {"projectId": "...", "columns": [{"status": "backlog", "cardIds": ["..."]}]} ``` **When to use:** Always. Check the board before starting work. Update it as you go. The user is watching this board to understand what you're doing. --- ### Todo — localhost:3143 A simple shared list with two columns: things to do, and things NOT to do. You can read both columns. You can only write to the todo column. The "not todo" column is written by the user — these are guardrails. Read them and respect them. If the user says "don't refactor the database layer," do not refactor the database layer. ``` GET / → {"todo": ["..."], "not_todo": ["..."]} POST / → {"todo": ["item 1", "item 2"]} ``` The POST replaces the entire todo list. Read the current list first, modify it, then write it back. Do not accidentally delete existing items. **When to use:** Check this when you need quick guidance on what to do next, or when you're unsure if something is in scope. The "not todo" list is especially important — it tells you what the user explicitly does not want. --- ### Help — localhost:3144 Send an alert to the user. The app plays a sound and displays the message. The user may not be looking at their screen. Three severity levels: - `critical` — something is broken or about to break. Production is down. Data loss is imminent. Use this rarely. - `urgent` — something needs attention soon. A test suite is failing. A deploy is stuck. A resource is almost exhausted. - `concerning` — something the user should know about but doesn't need to act on immediately. A pattern you noticed. A dependency that's outdated. A metric trending in the wrong direction. ``` POST / → {"level": "critical", "message": "one sentence describing the issue"} ``` **When to use:** When something goes wrong and you need the user's attention. Do not use this for status updates or progress reports — use Mail for that. Do not spam alerts. If you send too many, the user will start ignoring them. --- ### Mail — localhost:3145 Leave a non-blocking message for the user. This is asynchronous — you post a question or thought, the user answers when they feel like it, and you can check back later. This is for things that don't need an immediate answer. Architectural questions. Ideas for improvement. Things you noticed that might matter later. "Should we..." and "I was thinking..." messages. ``` POST / → {"question": "your message"} → returns {"id": 1} GET /:id → {"id": 1, "question": "...", "answer": "..."} or {"answer": null} GET / → list all questions and answers ``` **When to use:** When you have a thought, question, or observation that isn't urgent. When you want the user's input but can continue working without it. When you want to surface something for the user to think about later. **When NOT to use:** When you're blocked and can't continue without an answer — use the CLI for that. When something is broken — use Help. Check for answers periodically if you asked something relevant to your current work. --- ### Timer — localhost:3142 A pomodoro timer. The user sets a duration and starts it. You can check how much time is left. ``` GET / → "18:32 work" ``` The response is a string: `MM:SS` followed by a phase — `work`, `break`, `idle`, or `done`. **When to use:** When the user has given you a time-boxed task. Check the timer to understand urgency. If there are 3 minutes left and you're in the middle of a large refactor, wrap up what you have and don't start new work. If the timer says `idle`, there's no time pressure. --- ### Thought — ~/thoughts.md The user captures quick thoughts via a global hotkey. These are saved to `~/thoughts.md` with timestamps. ``` cat ~/thoughts.md ``` Each line looks like: `- 2026-04-06 15:30 — the thought` **When to use:** Read this file when you want context on what the user has been thinking about. It's a stream of consciousness — ideas, reminders, observations. It may contain hints about priorities, concerns, or directions the user hasn't formally communicated yet. Do not write to this file. It belongs to the user. --- ### General guidelines - **Check if apps are running before using them.** A failed request means the app isn't open — don't error out, just skip it. - **The Backlog board is the most important tool.** If it's running, check it first and keep it updated. - **The "not todo" list is a hard constraint.** Respect it completely. - **Help alerts are interruptions.** Use them only when the situation warrants interrupting the user. - **Mail is for async communication.** Use it freely for non-urgent things. - **The user is a collaborator, not a supervisor.** These tools exist so you can work together without constant back-and-forth in the terminal.