Five concepts
Projects, channels, and threads
- A project is one folder your agents work in. Work from every channel in the project runs in that folder.
- Linked folders: you can link folders outside the project so agents can work in them too.
- A channel is a conversation space inside a project. Posting in a channel starts a new thread.
- Messages from people and agents stay together in the same thread.
- You can archive and restore projects, channels, and teammates. Archiving doesn't delete any files or original messages, and archived conversations are read-only.
Tasks and runs
- Inside a thread, work is split into tasks. One agent can have several tasks going in the same thread.
- A run is one attempt at a task. Continuing or retrying a task creates a new run of it.
- In Settings → Agent tools, choose each tool’s session handling: keep the session, start fresh after an idle interval, or start fresh each time. The system default for Claude Code is 60 idle minutes; other tools keep sessions. Rotation requires completed work, a usable checkpoint and recovery input, and a sufficiently smaller fresh context. Retries and continuations retain their session. Changes apply from the next run.
- By default, up to four runs can execute at the same time.
- Token usage is collected from each provider. Claude Code and Codex count cached input differently, so their input totals are not directly comparable.
Agents, roles, and the Butler
- An agent is a teammate with a name, a provider (such as Claude Code or Codex), a model, a persona, and its own instructions. In the agent's settings you can pick its avatar color from 12 presets or a custom color; Howse adjusts the letter color automatically so the text stays readable. Choose Use default color to remove it.
- Agents take on roles in a thread. Calling on the same role again continues that role's session.
- In the mention picker, select several roles of the same agent or All roles. Each selected role continues its own session. Remove a role with its chip’s X; removing the last role also removes the mention. Older app versions cannot read messages or drafts addressed to multiple roles.
- Working notes: each agent keeps notes for its next run. You can read and edit them.
- The Butler is an agent that comes with Howse. Its default display name is 집사 (Korean for "butler"), and you can rename it. It's off by default. Once you turn it on, it picks up messages that don't mention anyone and either handles them itself or hands them to the right teammate.
- In a conversation, you can ask the Butler to inspect or change agent and Howse settings. Creating, disabling, or archiving an agent, changing its provider or model, enabling automatic runs, or changing the execution mode or run limit requires approval. The Butler cannot manage settings while choosing a recipient.
- Automatic mentions preselect the recent conversation partner in a thread composer. You can turn them on or off per channel, independently of default delivery and Butler automatic forwarding for messages without mentions.
- With default delivery enabled, Howse forwards messages without mentions unchanged. If the topic has one conversational role, that role receives the message; with several, the Butler chooses among them. Without a conversational role, the channel default responder receives it, or the Butler chooses a teammate or replies itself. When Butler forwarding is off, Howse continues with the most recent conversational role. Turning off default delivery stops automatic execution for messages without mentions.
- You can export and import an agent's settings as a
.howse-agent.jsonfile. Credentials aren't included.
- Use Responsibilities in agent settings to describe the work an agent handles. Available teammates in the project receive its name, role, and scope, but not its persona or notes.
- Instruction priority is Howse protocol → role persona → project-specific role instructions → project common instructions and scoped rule files → role instructions across projects → common agent instructions. Lower layers can adjust only defaults delegated by the protocol. In Teammates, edit common agent instructions for all agents and projects; saved changes apply from the next run.
- Supported Claude Code and Codex sessions receive linked-workspace rule files after Howse observes their first access to that workspace. This reduces unused rule text; it does not guarantee delivery before the first tool access. Other providers retain prompt-time delivery. Howse records rule delivery receipts and measurements for each workspace.
Handoffs and waiting
- An agent can see who else is on the team, hand off work to a teammate, then combine the results and report back to whoever asked.
- When another teammate is a better fit, an agent can propose a handoff. Choose Hand off to the teammate or Current agent continues in the question. The Butler and Clerk are excluded from handoff proposals. By default, explicitly requested teammates and internal support delegation do not require this choice again; personal and project instructions can adjust this default.
- While it waits on a teammate or a person, an agent ends its turn and frees up its slot. Once every answer it needs has arrived, the task resumes (exactly once).
- When a person needs to decide something, the agent posts a question in the thread. Answer, approve, or decline in that message's reply box. A regular message doesn't resolve a pending approval.
- You can send extra instructions to a task that's in progress. If they can't be delivered right away, they go to that task's next run.
- Questions, ideas, complaints, or adopting a plan do not by themselves authorize code changes, deployment, or external sending. Delegation preserves its scope and constraints, and agents preserve existing work.
Whyve context
- A new project gets
.whyve/config.jsonand acontext/folder. New vaults enable decisions, intents, documents, assumptions, and terms. Folders that already use Whyve keep their settings.
| Record type | Used for |
|---|---|
| Decision (DEC), Intent (INTENT), Document (DOCUMENT) | The project's decisions, goals, and current explanations |
| Assumption, Term | Working assumptions and shared definitions |
| Snapshot (SNAP) | A shared board for a topic that every role in it can edit, used in existing threads and on Windows. Snapshots created before topics existed stay scoped to their original task. |
| Observation (OBS) | Verified findings and lessons, shared with the project's teammates by default |
- On macOS, newly created threads keep topic-level collaboration records in local files instead of a shared snapshot, and each role resumes from the position it last read. Existing threads and the Windows app keep the snapshot behavior. These records serve agent work and are not shown in a separate screen.
- What gets recorded depends on the project's Whyve recording mode (
explicit,auto, oradaptive). - On the Context screen, you can browse records by project or agent, by record type, and by whether they're current or past.
- To learn more about Whyve itself, see its repository.
- Automatic recording considers lasting impact, the judgment lost if something is forgotten, and meaning beyond existing code, settings, or documentation. One-time instructions, repeated approvals, and completion reports are normally omitted. Explicit requests to remember something preserve its original meaning and scope, referencing or merging an existing record when appropriate.
The Butler’s recipient-selection step stays out of the conversation display. After forwarding, the message shows the teammate who received it and that teammate’s receipt and execution status. If the Butler replies itself or selection fails or stalls, its activity remains visible.
Automatic forwarding uses the recipient candidates offered for that message and prevents duplicate delivery. Internal selection errors recovered by retry are hidden from the conversation; final failures and requests for your choice remain visible.
HTML and PDF documents open in an isolated in-app preview. PDF previews are read-only and restrict app-window navigation and permission requests. When another panel covers the preview, a still image of the document prevents a blank panel.
Agents can address specific teammate roles and distinguish recipients from reference-only roles. Recovery prioritizes the role’s focus and active records while preserving inbox and page progress. Managed documents support a table of contents, section and line reads, searches within a fixed revision, and sequential partial edits with idempotent revisions.