Projects and coordinators
A project collects every conversation from one repository or folder, whatever harness you used. Open a project’s overview to see its recent and active work, start, resume, and message the agents working in it, and give the project a coordinator: a persistent Codex or Claude Code conversation that remembers the project’s goals and hands work to helper agents. The coordinator chat is available only in the app.
- App
- Sessions → project overview, Projects
- CLI
hansard projects, hansard coordinator, hansard stats --repo
Open a project in the app
Section titled “Open a project in the app”-
Select Sessions in the dock.
-
Select a project’s name. The project overview opens with the project’s folders, conversation count, last activity, and the harnesses you used there. Folders synced from your other devices show that device’s name before the path. In the app, the coordinator chat fills the main column and the conversation groups sit beside it. On a narrow window the groups move below the chat. Select Memories to see the memories saved for the project, or Board to open the project’s message board.
-
Review the conversation groups:
- Pinned lists conversations you pinned.
- Waiting on you lists runs that need your approval or reply, runs that failed or were interrupted, and sessions that reported they are blocked or need review.
- Working lists runs in progress.
- Resolved lists finished runs and sessions that reported they are done.
- Recent conversations lists the rest. Select Show more below the list to add the next conversations in place.
Each conversation appears in one group, so the group counts add up to the conversation count in the header. Runs whose conversation is not archived yet count too.
A conversation or run that edited files shows the lines those edits added and removed under its time, for example +120 −34. The counts add up the diffs on the conversation’s file edits. An edit that failed still shows its diff in the conversation but is not counted, and neither is a diff that a command only prints, such as
git diffoutput. For conversations archived before these counts existed, runhansard rebuild --since allonce to add them. -
To start a conversation in the project’s folder, select New conversation.
To open the conversation you last viewed instead of the overview, go to Settings → General, find When you open a project, and choose Last viewed conversation. A project without a viewed conversation still opens its overview.
Start and message the project’s agents
Section titled “Start and message the project’s agents”The project page also keeps track of every agent working in the project’s folders, whichever harness and terminal it runs in. Agents you start in a terminal yourself join the list as soon as Hansard sees them running. The watcher follows their state without any model request.
- Select Start agent at the top of the page. Choose the Harness, the Model, Effort, and Permissions in the harness’s own names, a Speed for Codex, the Folder, and where it Opens in: a Hansard conversation, a Hansard terminal, or a new tab in cmux, Terminal, iTerm2, or Ghostty. Write its First message, then select Start agent. Settings you leave alone follow the harness’s own configuration. Terminal support lists what Hansard can do with an agent in each terminal.
- Review the groups above the conversation groups:
- Needs you lists agents waiting at an approval or a question, with Show tab or Open to answer them, and decisions agents asked you to make, with a button for each answer.
- Agents lists the running agents with their state and latest detail. Agents that stopped when the computer restarted offer Resume. Message several sends the same words to the agents you pick.
- Follow-ups lists what agents scheduled for a time, a commit, or another agent finishing.
- Activity lists what the watcher noticed, such as an agent waiting, stopping on an error, or finishing, a board reply, or a commit. Watches chooses which events notify you or wake the coordinator.
- Select an agent to open it in the main column: its folder, harness, model, where it runs, and its latest messages. Write in the message box to send it your exact words. Hansard types them into a cmux tab or a tmux pane, sends them to Claude Code through its own inbox, or leaves a Hansard message, as Type messages into an agent describes. Show tab brings its cmux tab forward, Open opens its conversation, and Stop or Resume stops or reopens it. An agent started in a Hansard terminal also offers Terminal to work in that terminal.
Codex and Claude Code sessions use the same records through five tools,
start_agents, deliver_message, roster, ledger, and run_metrics, which they get
with the helper agent tools.
From the CLI, hansard coordinator covers the same records:
hansard coordinator statushansard coordinator metrics --jsonhansard coordinator start codex --brief "Review the parser tests" --in terminalhansard coordinator start claude --environment example/local --brief "Update the API client"hansard coordinator send <roster-id> --text "Also check the narrow layout."hansard coordinator resume --allRun them in one of the project’s folders, or add --project <key>. status
also shows each agent’s tokens and estimated cost over the last 24 hours.
metrics reports per-run counts of messages, board posts, directed pairs, hub
share, first-message timing, refusals, duplicates, empty messages, tool calls
between messages, and the run outcome. --after and --before accept ISO
timestamps. --environment starts the agent in a project environment, with
its folders, setup command, and defaults.
hansard help coordinator lists the decision, follow-up, workstream, and
watch commands.
These commands act for you. Inside an agent session, start, send, settings
changes, and changes to decisions and watches refuse, and an agent uses its
start_agents, deliver_message, roster, ledger, and run_metrics tools instead.
start, send, and decisions answer also need an interactive terminal, or
use the project page in Hansard. start reads a brief only from --brief or
--brief-file, and send reads its words only from --text or --text-file,
never from piped input.
Every 30 seconds, the watcher checks agent state, held messages, matching commits, followed board threads, due follow-ups, and answered decisions. These checks make no model request. A watch can record an event, notify, or wake the coordinator with a digest. Wake digests are off until enabled:
hansard coordinator settings --wake onhansard coordinator watches add --kind usage_pace --then notify --fields '{"params":{"usd_per_hour":20}}'A manually added watch can send continue after a capacity or connection
failure, at most three times. An approval covers one action and target and is
used once. Agents cannot answer decisions. Roster records stay on this device
and never sync. Tokens and estimated API cost describe recorded activity, not
subscription limits.
Manage projects in the app
Section titled “Manage projects in the app”

Select Projects in the dock to manage your projects. Hansard makes a project from each GitHub repository your agents worked in, and puts it in the organization named for the repository’s owner. Projects without a GitHub repository go in Personal.
The sidebar lists each organization. Its portfolios come first, each with its projects, and then its other projects. Below the organizations, Shared with you lists what teammates shared with you, and Not in a project lists folders without a GitHub repository that belong to no project yet. A project shows a dot and a count while its conversations need you, from the same groups as the Running view.
A project’s page shows its coordinator under the figures at the top: the same coordinator chat, agents, decisions, follow-ups, and Start agent as the project overview.
To make a project from a folder:
- In Not in a project, select the folder. Its page lists its recent conversations.
- Select Create project, enter a Name, and choose a Portfolio if you want one. The project starts with one environment, Local, that opens the folder on this device.
To add the folder to a project you already have, select Add to a project instead.
To keep a repository’s project out, open it and select Hide project in the More actions menu. The organization’s page lists its hidden projects. To bring one back, select Restore.
A project’s page holds these sections:
-
Environments say where agents work on the project. Each row names the folders it opens, and a status when a folder is not on this device. Select one to open Edit environment: its name, its folders with the branch each has checked out on this device and the one agents start in, Worktree on the start folder for a new worktree for each conversation, the names of the environment variables it needs (each says whether this device sets it, and values stay on each device), the default agent and account, and a setup command. Claude Code, Codex, and Cursor CLI open every folder of an environment. Other agents start in the start folder and get the other folders’ paths in their first message. Environments run on this device. SSH hosts and cloud runs are not available yet.
-
Plugins lists the skills, plugins, and MCP servers agents get in each environment, each with a switch. Select Add plugin to add one from a marketplace your agents already use, from a GitHub repository (
owner/repo) or git URL, or from a folder on this device. Hansard keeps its own copy and turns the plugin on in that environment. It never changes your agents’ own settings. Select a plugin’s name to see what it provides, how often your agents used it, and which environments turn it on. Each agent gets what it can load for one launch:Agent Gets Claude Code The whole plugin. Cursor CLI The whole plugin, when it has a Claude Code or Cursor manifest. Codex The plugin’s MCP servers, with its skills named in the first message. OpenCode The plugin’s MCP servers and skills. Grok Build, Devin, and Antigravity The plugin’s skills, named in the first message. -
Memory files lists the instruction files and agent memories in the project’s folders. Select one to open it in Memories.
-
Under Environments, a row names the folders that are not on this device, with Set path to tell Hansard where one is, and Account chooses the sign-in that new conversations start under.
-
Sharing has one row for each Team you belong to, with a permission. View shows the Team’s members the project’s environments, plugin lists, and memory file names. Use also lets them start conversations with its environments. Edit and Manage are listed but not available yet. Teams never receive file contents or folder paths. A permission that an organization or portfolio gives shows on its projects, and you change it there.
-
Folders lists the folders whose conversations belong to the project, and suggested folders you can Add or Dismiss.
The header’s Stats opens the project’s charts, which match the Stats page scoped to the project. Open overview opens the project overview described above, and New conversation starts a conversation in the default environment. The More actions menu renames the project, moves it to another organization or portfolio, hides a project that Hansard made from a repository, or deletes it. Deleting a project never deletes conversations. Its folders become suggestions again, and a project that Hansard made from a repository does not come back.
Select a portfolio’s name in the sidebar to see its projects, the defaults new projects in it take, and its sharing. Its Stats covers every project in it. Select an organization’s name to see its portfolios, its other projects, its hidden projects, and its sharing. To make an organization of your own, select New organization in an organization’s More actions menu. You can share an organization with a Team as a whole.
Folder paths stay on each device. Personal Sync carries projects, environments, portfolios, and the plugins Hansard keeps to your other devices, and each device finds a repository’s folder by its remote. A plugin added on another device shows Install until this device has a copy. Path-based Rules that group automation run folders stay in Settings → Projects.
When an environment creates a worktree for a conversation, Hansard keeps it
under <HANSARD_HOME>/worktrees, on a new hansard/ branch. Later turns and resumes use that same folder.
Hansard never removes a worktree the conversation used. The environment’s setup
command must succeed before the agent starts.
Manage projects from the CLI
Section titled “Manage projects from the CLI”hansard projects reads and changes the same records as the Projects
page. Environments are named <project>/<environment>.
hansard projects list # organizations, portfolios, projects, and folders in no projecthansard projects show example # a project's environments as this device resolves themhansard projects plan example/local --harness codexhansard projects bind example/local api ~/code/apihansard projects share project example <team-id> viewplan starts nothing. It prints the start folder, the other folders, the
flags each agent gets, the setup command, and what the agent cannot apply.
bind tells Hansard where one of an environment’s folders is on this device.
share takes a Team ID from hansard projects list --json, and off stops
sharing. hide and restore
keep a project Hansard made from a repository out or bring it back, and add
and dismiss act on a suggested folder. Run hansard help projects for every
command and option.
Choose coordinator settings in the app
Section titled “Choose coordinator settings in the app”A coordinator is one long-running conversation per project. It keeps track of the project’s objective, accepted decisions, and unfinished work across turns and app restarts. Every project’s coordinator uses the same settings, so there is nothing to set up per project.
- Open Settings → Coordinator.
- Choose the Harness: Codex or Claude Code. A harness that is not installed on this device, or is turned off under Continue in in Settings → Handoff, cannot be selected.
- Choose the Model and Reasoning effort in the harness’s own names. Chosen by the harness uses the harness’s own setting and names the value it resolves to when it is known. To use a model the list does not include, choose Other model and enter its ID.
- For Codex, choose the Speed: Standard, Fast, or, when Codex offers it for the model and account, Ultrafast. Left unset, the coordinator follows Codex’s own setting.
- Set the Helper budget, from 1 to 100 with a default of 32.
Changes save as you make them and send nothing to a model. They apply from each project’s next message. Changing the Harness continues each coordinator’s work in a linked conversation in the new harness once its current conversation has been archived. A model or effort change waits for a running turn to finish.
The first message you send from a project overview creates that project’s coordinator. It runs in the project’s most recently active folder on this device. A project can also keep its own Project brief of up to 8,000 characters: goals, success criteria, priorities, and conventions. Edit it in Scratchpad at the top of the chat. The coordinator reads it when its conversation starts and whenever the brief changes.
A project whose folders are only on your other devices has no coordinator on this device. Its overview names the device to open Hansard on instead.
Work with the coordinator
Section titled “Work with the coordinator”- Type in the message box at the bottom of the coordinator chat, then press
Enteror select the send button. PressShift+Enterfor a new line. A new coordinator offers a few starting prompts; selecting one fills the message box without sending it. - Read the replies in the chat. The status next to Coordinator shows Ready, Working, Waiting on you, Paused, or Message not sent.
- When the coordinator is waiting on you, select Open waiting decision in the chat to approve a tool call or answer a question. Select Open conversation at the top of the chat to read the full conversation and steer it. When the coordinator’s own conversation edited files, the line below Coordinator also shows the lines those edits added and removed. Select the harness name in the message box to change the harness and model in Settings → Coordinator.
The chat shows the coordinator’s whole conversation, including the conversations it continued after a harness change. Threads it started appear in the chat where it started them. A very long conversation shows its most recent 400 messages and links to the full conversation.
Messages you send while the coordinator is busy wait in a queue and appear as Queued. Select Discard to remove a queued message before it is sent.
The coordinator can search memories and archived conversations from every harness and project, then read the relevant parts. It checks the current files before acting on what it finds.
Its context includes a short preview of recent conversations, live peers, reported blockers, and delegated work, with links to source conversations. Reports older than 30 minutes keep their last stated status but have an unknown current state. A title never establishes that an agent is currently working. Opening the project or saving its brief makes no model request.
Agents can find the coordinator through list_peers or session_context.
A notification to an idle coordinator leaves an inbox note without starting
a turn. Discovery reports missing or unavailable coordinators without
launching one.
Keep decisions and verify tasks
Section titled “Keep decisions and verify tasks”Scratchpad holds the project brief, saved rules, and decisions. Review, edit, or delete entries there, or ask the coordinator to remember a preference. Rules can name a harness and model. When a newer model appears or a saved model disappears, the coordinator offers the rule for review. Suggestions never change saved preferences automatically. These records stay in private coordinator data and do not edit provider memory files.
Task plan records the objective, assignments, file scopes, dependencies, blockers, and acceptance criteria. Queued workers reserve their declared file scopes. Overlapping assignments wait for verification or a scope change.
A finished worker becomes Needs review. Mark verified requires a
successful check and review note for every acceptance criterion. Evidence
records file hashes. A changed file or a new worker attempt requires another
review. The coordinator manages this plan through coordinator_plan and passes
plan_task_id when delegating a planned task.
An interrupted worker offers Inspect and resume. It resumes the existing conversation with instructions to inspect completed work and continue unfinished steps. Hansard does not replay earlier commands. Recovery keeps its request identity across reloads, and paused or stopped work stays stopped. Task plans and output files need no archive rebuild or reimport.
Follow threads
Section titled “Follow threads”When helper launches are on, the coordinator hands substantial tasks to helper agents in the same project. Helpers can start their own helpers, so work forms a tree. Each helper’s work is a thread.
Threads appear above the conversation groups beside the chat, indented under the helper that started them. Each thread shows its status (Queued, Working, Done, Failed, or Stopped) and one line: its result once it has one, its task before that. A thread whose conversation edited files shows the lines those edits added and removed in that line, counted the same way as the overview’s rows. Select a thread to open its conversation, or its live run while it is working.
When a helper finishes, Hansard delivers its result to the helper or coordinator that started it, once, even across app restarts.
These limits apply:
- The Helper budget counts the project’s helpers that are waiting to start or running. Finished helpers do not count, so a helper refused at the budget can start once another one finishes. Raise it in Settings → Coordinator when the project needs more at once.
- The global helper limits in Helper agents also apply, including how deep helpers can nest.
- When more than one run can execute at a time, helpers leave one slot free so the coordinator can still answer you.
Pause or stop work
Section titled “Pause or stop work”Pause scheduling, Resume scheduling, and Stop all work are in the More coordinator actions menu at the top of the chat. While the coordinator is working, Stop all work also appears in the chat.
| Control | Effect |
|---|---|
| Pause scheduling | Starts no new work. Running turns finish, and queued messages and results wait. Send is unavailable until you select Resume scheduling. |
| Stop on a thread | Cancels one thread and every helper under it, and discards queued messages and results for them. |
| Stop all work | Cancels the coordinator’s current turn and every thread, discards queued messages, and pauses scheduling. Select Resume scheduling to continue. |
View project stats from the CLI
Section titled “View project stats from the CLI”The coordinator chat, its threads, and the project overview have no CLI
commands; hansard coordinator covers the project’s agents. To view one
project’s statistics in the terminal:
hansard stats --repo github.com/example/appSee Stats for the other options.
Troubleshooting
Section titled “Troubleshooting”The coordinator chat is missing. You opened a portfolio instead of a single project, or the app is in read-only mode and the project has no coordinator. Coordinators need a writable local app and an individual project. A read-only viewer shows an existing coordinator’s messages and settings but cannot send.
The coordinator does not respond. Work runs only while the app or
hansard web is running on this device. Check whether Paused appears next
to Coordinator, and select Resume scheduling.
A helper cannot start. The project may have as many helpers running as its Helper budget, or Helper agents may be off. Raise the budget in Settings → Coordinator, or turn on Settings → Collaboration → Agent messaging → Helper agents.
A message says the harness is not available. The harness chosen in Settings → Coordinator is not installed on this device or is turned off under Continue in. Choose the other harness, or install or turn on the chosen one.
The overview asks you to choose a coordinator. Two projects that each had a coordinator were combined. Select the coordinator to keep.