How Clarvis works
Understand agents, sessions, plans, and the other parts of a Clarvis task.
Start with the operator loop
Clarvis helps you work on a project from the terminal. Choose an agent, a model, and safety settings, then describe the result you want. The agent can inspect files, use tools, change code, delegate work, or ask questions. You set the goal and decide which actions it may take.
workspace -> session -> run -> lead agent -> tools and sub-agents -> resultA workspace is the project directory Clarvis is operating on. It determines which project files, workspace configuration, and session history are in scope.
A session is the durable conversation for that workspace. It keeps the transcript and usage across multiple turns. /sessions opens session history, /export writes the complete persisted transcript, and /clear archives the current session before starting a fresh one.
A run is the active execution that follows one submitted task. While it is active, new input steers that work instead of creating a competing run. /status shows the current agent, model, run state, token usage, and cost.
Agents define how work is done
An agent profile defines its system prompt, model, reasoning effort, tool permissions, budget, and ability to delegate. You can replace the full system prompt of any built-in agent. Use /agent to choose the lead for the next run or /settings/agents to edit a profile.
The lead owns the final response. When delegation is available, it can send a planned task to a sub-agent or spawn independent bounded work. Each child has its own profile, context, tools, and budget. Results flow back to the parent; the activity view and transcript show who owns each branch, its current state, and its completion result.
Delegation is useful when work can proceed independently. It is not free parallelism: every child uses model context and tools, so the lead should delegate a clear objective and avoid duplicating the same investigation.
Workflows make orchestration reusable
A workflow saves a sequence of work for several agents. Use one when you want to repeat the same process, such as an investigation followed by implementation and review.
Type /workflow to browse current and previous workflow runs and inspect their manager-to-agent trees. Workflow definitions live in built-in, global, or workspace catalogs and are selected when Admiral starts a workflow. A workflow organizes execution; the session transcript still records what happened, and ordinary safety controls still apply to every tool call.
Plans make intent inspectable
A plan is the ordered execution record an agent uses to break an outcome into verifiable work. With normal planning, the agent can create and follow it during the run. With plan review enabled, Clarvis pauses after the proposal and waits for your decision before implementation begins.
Plans are not workflows. A plan describes the steps for one objective; a workflow defines a reusable manager-and-leader structure that can launch several focused runs. Press Ctrl+P to inspect the current or latest plan and use /plan to toggle required review for the workspace.
Memory carries project knowledge forward
Memory is a workspace-local Markdown wiki, separate from the session transcript. At run start, its bounded root summary gives agents durable project knowledge. After a run, a background indexing pass decides whether verified commands, decisions, pitfalls, or other non-obvious knowledge deserve a coherent update. Most runs need no memory change.
Because the wiki is plain Markdown rather than a vector database, you can inspect and edit exactly what future runs may reuse. Configure it in /settings/memory and use memory-policy.md to say what is worth retaining.
Tasks connect an external source of truth
Tasks is an optional connection to an external task service. /tasks shows its work items without copying them into a Clarvis task database. Choose Work on task to start an agent run linked to that item in your current project.
Reading and changing tasks are separate permissions. Writes are disabled by default and require work mode, matching agent grants, and provider support. Completing a Clarvis run never changes an external task's lifecycle automatically.
Extension Profiles define the active capability set
Plugins can add agents, tools, hooks, and other services. Skills provide reusable instructions. An Extension Profile lists which installed plugins and independent skills are available to new runs.
You can keep separate profiles for research, coding, review, or other kinds of work, and switch between them within the same workspace. Global profiles can be reused across workspaces. Each custom profile includes only its selected extensions.
Open /extensions to find extensions and choose your active set. The guided editor lets you review changes before applying them. The Plugins browser also offers an explicit install-and-activate action. Repository-owned executable content needs workspace approval. Clarvis records the profile and its content fingerprint with each run and session.
Context is smaller than the transcript
The persisted session is the durable record. The model context is the bounded working set sent to a model call. Clarvis may fold older transcript content out of the live view and compact older context so an active session can continue without sending everything again.
Use /compact when you want to request that deliberately. Add a short preservation instruction when specific decisions must survive:
/compact preserve the accepted API shape and the unresolved Windows failureCompaction does not replace the persisted transcript. Use /export when you need the complete record, including material no longer mounted in the live view.
Follow one run from start to finish
- Clarvis resolves effective global/workspace configuration and the selected Extension Profile.
- You select the lead agent and safety settings for the next run.
- Your prompt, or an external task you chose to work on, starts a run inside the current session.
- The lead can create a plan, call allowed tools, and delegate bounded work.
- Clarvis pauses for required command, plan, workflow, or user decisions.
- Child results return to their parent, and the lead produces the final response.
- The session retains transcript and events for resume or export.
- When configured, memory queues a background review of durable knowledge after the run.
If the effective configuration cannot start safely, /doctor explains the blocking check and offers the relevant repair surface.
Terms used in these docs
| Term | Meaning |
|---|---|
| System prompt | The instructions that define an agent's role and way of working. You can replace the built-in agent prompt in full. |
| Skill | Reusable instructions, with optional scripts and reference files, loaded when needed. |
| MCP | Model Context Protocol: a way to connect tools and information from other services. |
| Hook | An action triggered by an event, such as a tool call or the end of a run. |
| Snapshot | A fixed version of the extension set used by a run. |
| Fingerprint | An identifier calculated from content, used to detect when that content changes. |
| TUI | The interactive interface you use in the terminal. |
| Kernel | The part of Clarvis that manages a project's runs, tools, and settings. |