Agent System

The desktop app uses a two-phase agent system where every task goes through planning and execution. Each agent can be configured with a soul personality that defines its identity, communication style, expertise, and boundaries. This gives you full visibility and control over what the AI agent does before it acts.

Two-Phase Workflow

Phase 1: Planning

When you submit a task, the agent analyzes your request and proposes a structured plan:

1. You enter a prompt describing what you want done
2. The agent thinks and creates a step-by-step plan
3. The plan is displayed with details about:
   • Steps to complete
   • Files to create or modify
   • Tools the agent needs to use
   • Scope of changes
4. You review the plan and can approve, modify, or reject it

Phase 2: Execution

Once you approve the plan, the agent executes with full tool access:

1. The agent begins working through the plan steps
2. Progress streams in real-time as the agent:
   • Creates and modifies files in your workspace
   • Executes code in sandboxed environments
   • Calls tools (Linear, Google, media generation, etc.)
   • Reports progress and intermediate results
3. You see everything -- tool calls, file changes, and agent reasoning
4. Results appear in the task view and generated files go to the Library

AI Backends

The app supports multiple AI backends. You can choose which one to use based on your needs:

All backends provide the same consistent experience:

• Plan-then-execute workflow
• Workspace isolation
• Real-time streaming
• Session management

Settings > Agent Runtimes can also detect and help install additional local command-line runtimes, including Qwen, Devin, Kilo, Mistral Vibe, DeepSeek TUI, GitHub Copilot CLI, Kiro, Kimi, Hermes, and Pi. Availability depends on your operating system and what is installed on your machine.

The runtime settings page can test a local runtime connection and distinguish a missing CLI from an authentication problem. Codex and Pi also expose reasoning controls, and Pi runs through its local RPC mode when available. Qoder CLI is available only when your workspace enables the experimental Qoder runtime flag.

Tool Compatibility

MCP tools (see MCP and Skills) work across backends. Claude supports MCP natively, while other backends use an automatic compatibility layer -- no configuration needed on your part.

Built-in Tools

During execution, agents have access to a wide range of tools:

Sandbox Execution

Agents can run code in sandboxed environments with up to 5 concurrent instances. The sandbox provides safe script and command execution within your workspace boundaries.

Execution Modes

Standard Mode

The default mode where the agent reasons through each step sequentially. Best for complex tasks that require careful decision-making.

Batch Mode

An optional mode for efficient bulk operations. When the agent detects many similar repetitive actions, it can process them in a batch instead of one at a time. Enable this in Settings > General.

Session Management

Each task runs within a session that provides:

• Isolated state -- Sessions don't interfere with each other
• Abort control -- Cancel a running task at any time
• Health monitoring -- Detects if the agent gets stuck during thinking
• Automatic cleanup -- Stale sessions are cleaned up after 1 hour of inactivity

V2 Streaming Thread

The app includes an enhanced task view with richer interactivity and smoother real-time streaming.

Interactive Question Cards

When the agent needs clarification, it displays an interactive card instead of plain text:

1. The card shows the question with a descriptive header
2. Click one or more option buttons to select your answer
3. Use the "Other" option to type a custom response
4. Click Submit to send your answers back to the agent
5. After answering, the card shows a read-only summary of what you chose

Inline Plan Approval

Plan proposals in the V2 view appear as inline cards:

1. The agent creates a plan and pauses
2. A card appears showing the plan goal and numbered steps
3. Click Approve to resume execution or Reject to decline
4. The agent continues based on your decision

Per-Task Model Selector

Each task has its own model picker in the chat input:

• Switch AI models for the current task without affecting other tasks
• Your choice is remembered across sessions
• When starting from a profile, the profile's model is pre-selected

Live Catch-Up

If you open an in-progress task in another tab or after a page refresh, the full conversation history is replayed automatically so you never miss context.

Task Queuing

Each agent profile has a concurrent task limit that controls how many tasks it can run at the same time (default: 1). When you submit a new task and the profile is at capacity, the task is automatically queued instead of rejected.

How It Works

1. You start a task assigned to a profile
2. If the profile has a free slot, the task begins immediately
3. If all slots are in use, the task enters a queue and you see its position
4. When a running task finishes, the next queued task starts automatically

Queue Priority

Tasks are processed in priority order. Within the same priority level, tasks run first-come, first-served. Queued tasks can be viewed on the Home page's Parallel Task Dashboard.

Parallel Task Dashboard

When multiple tasks are running or any tasks are queued, a status strip appears at the top of the Home page. Each running task shows its title, elapsed time, and cost. You can navigate to any task or stop it directly from the dashboard.

Dispatch Mode (Background Tasks)

From the Home page, you can dispatch tasks to run entirely in the background:

1. Type your prompt in the chat input
2. Click the rocket button (next to the send button) instead of the regular send
3. The task starts in the background with auto-approval enabled -- no plan review needed
4. You stay on the Home page and can start more tasks immediately

Background tasks appear in a dedicated section on the Home page:

• See a snippet of each task's prompt and how long it's been running
• Click a task to open the full task view at any time
• Stop running tasks or dismiss finished ones

Dispatch mode is ideal for tasks that don't need your immediate supervision -- long code generation, research runs, or batch operations.

What You See During Execution

As the agent works, you'll see different types of updates in real-time:

• Text responses -- The agent's written output
• Thinking -- The agent's reasoning process (when visible)
• Tool calls -- When the agent uses a tool, and the result it gets back
• Plans -- Structured plan proposals for your review
• Question cards -- Interactive multi-choice cards when the agent needs your input (V2)
• Quick answers -- Direct responses that don't need tool use
• Errors -- Any issues that occur, with context

Live Artifact Preview

When an agent generates HTML pages, SVG graphics, diagrams, code, or markdown documents, a live preview appears directly in the chat — no need to open a separate file. The preview updates in real-time as the agent streams its output.

Supported artifact types:

When the agent produces multiple artifacts in one task, a tab strip appears above the preview so you can switch between them. The most recently updated artifact is selected automatically.

Inline file preview: If the agent mentions a file it created or modified in your workspace, a preview of that file appears directly in the conversation — images, SVGs, markdown, HTML pages, and text files all render inline.

To enable live artifact previews, go to Settings > General and turn on Artifacts V2.

Trace Viewer

The Trace tab in the workspace panel provides a detailed operation timeline:

• Metrics bar: Total duration, input/output tokens, total cost, and operation count at a glance
• Type filters: Show or hide LLM calls, Tool calls, Thinking, User messages, Errors, and Plan steps
• Timeline: Each operation appears as a row with a colored icon, name, relative duration bar, and optional token/cost badges
• Expandable details: Click any entry to see its full content and model information
• Live updates: During a running task, the timeline auto-scrolls and durations update in real-time

Cost Tracking

Every task tracks its cost so you can monitor spending:

• Cost per message in dollars
• Token usage breakdown
• Which model was used
• How long it took

This information appears in the task view toolbar.

Context Awareness

The agent receives contextual information before each task:

• Date and time with your timezone
• Language preference
• Platform details (OS, architecture)
• Location (approximate, privacy-preserving -- rounded to ~1 km)

This helps the agent provide relevant, timezone-correct responses.

Agent Profiles

Agent profiles let you create pre-configured agent personas for different tasks. Each profile defines:

• Identity: Name, role, description, and a role-based avatar (75+ icons, 12 color themes)
• AI Backend: Which backend to use (Claude, Gemini Local, etc.)
• Configuration: Default model, tools, skills, and system prompt
• Delegation rules: How many tasks it can handle, depth limits, and which other profiles it can delegate to

Soul Personality

Each agent profile can have a soul -- a structured personality framework that shapes how the agent thinks, communicates, and behaves. A soul has six pillars:

Applying a Soul Template

To quickly give an agent a personality:

1. Go to the agent's Profile Detail page
2. Click Choose Template in the Soul section
3. Browse the available templates (Developer, Writer, Analyst, etc.)
4. Click Apply to set the personality
5. Optionally edit individual pillars to customize further

Templates come pre-localized in English, Chinese, Spanish, French, Hindi, and Portuguese.

Soul Evolution

When evolution is enabled, the agent learns from your feedback:

• Corrections -- When you tell the agent "no, not like that" or "that's wrong," it remembers the mistake and the correct approach
• Learnings -- The agent detects patterns from successful interactions and records them
• After enough corrections accumulate, the agent can propose updates to its own personality -- adjusting its communication style, adding new expertise areas, or refining escalation rules
• Core values and hard boundaries are never changed -- only the agent's style, preferences, and approach evolve

You can view the agent's correction and learning history in the Evolution tab of the soul editor.

Importing and Exporting Souls

Share agent personalities between profiles or back them up:

• Export: Download a soul as a JSON file, including all corrections and learnings
• Import: Upload a previously exported soul to any profile

Thinking Configuration

Each profile can have a default thinking setting that controls how much the agent reasons before responding. This affects the depth and quality of the agent's planning and execution.

To configure thinking for a profile:

1. Go to the profile's Detail page
2. Find the Thinking section in the sidebar
3. Select a mode and adjust settings as needed
4. Save the profile

When you start a task, the profile's thinking setting is applied automatically. Per-task thinking settings (if provided) override the profile default.

Creating a Profile

When you click New Agent in the Agent Profiles page, a guided 4-step wizard walks you through setup:

1. Choose a Specialty -- Browse pre-built templates like Fullstack Developer, Code Reviewer, QA Engineer, or Security Auditor. Each comes with a role-specific icon, default skills, and a personality. Or choose "Custom" to start from scratch.
2. Personalize -- Set the agent's name, pick an avatar (75+ icons, 12 colors), choose a role, add a description, and optionally write a system prompt.
3. Configure -- Select the AI runtime and model, adjust thinking depth, edit the soul personality (Identity, Voice, Cognition, and Boundaries tabs), toggle MCP servers and skills (with the option to allow all or restrict to specific ones), and set the concurrent task limit.
4. Review & Create -- See a summary of everything you configured, including a soul preview. Click the edit icons to jump back to any step. When ready, click Create Profile.

After creation, you land on the full Profile Detail page where you can fine-tune any setting.

Skill Restrictions

By default, agent profiles have access to all installed skills. You can restrict a profile to use only specific skills:

1. Go to the profile's Detail page and open the Tools tab
2. Toggle All Allowed to switch to Restrict mode
3. Select the specific skills you want this profile to use
4. Save the profile

When skills are restricted:

• The agent can only use the skills you've selected -- no others
• If you restrict skills but don't select any, the agent runs with the most limited tool set (no skills, and built-in capabilities like media generation and speech are also disabled)
• Skills that were previously selected but have since been uninstalled appear with a "remove" option so you can clean them up

Skill restrictions apply everywhere the profile is used, including when the profile is assigned to a bot channel. This means a Slack or Telegram bot using a restricted profile will have the same skill limitations as desktop tasks using that profile.

Using Profiles

1. Go to Agent Profiles in the sidebar
2. Select a profile on the Home page dropdown before starting a task
3. The profile's configuration is applied to the session automatically

Task Assignment

Tasks can be assigned to agent profiles:

• From the Task Detail page, use the "Assigned Agent Profile" selector
• Profiles track how many tasks are assigned and their current status

Delegation

Agents can delegate subtasks to other agents:

• Delegation creates a parent-child task link
• Depth limits prevent runaway delegation chains (default: 3 levels)
• You control which profiles can receive delegated work

Templates

Templates are pre-configured assistant presets that give you a quick start for common tasks:

1. On the Home page, click Start with Template
2. Browse templates by category: Development, Writing, Research, Data, Design, Operations
3. Search by name or description
4. Click a template to prefill the chat with its starter prompt

Built-in templates include Code Review, Documentation Writer, Research Assistant, Data Analyst, Design Consultant, and QA Engineer.

Tool Permissions

When an agent needs to perform a potentially sensitive action -- like running a shell command, writing to a file, or making a network request -- you'll see a permission dialog before it proceeds.

Permission Dialogs

Each permission request shows:

• Risk level -- A colored badge indicating low, medium, or high risk
• Tool name -- Which tool the agent wants to use
• Command preview -- What the agent intends to do (truncated for readability)

You have three options:

• Deny -- Block this specific action
• Allow Once -- Let the agent proceed this one time
• Always Allow -- Auto-approve this tool for the rest of the session

If you deny the same tool multiple times, the agent will automatically try a different approach instead of asking again.

Configuring Permission Rules

In Settings > Permissions, you can pre-configure which tools are allowed, denied, or always require approval:

• Always Allow -- Tools that auto-approve (default: reading files, searching code, editing files)
• Always Deny -- Tools that are permanently blocked
• Always Ask -- Tools that always show a permission dialog

Rules support pattern matching:

• Bash(npm test) -- Allow only Bash commands containing "npm test"
• Read(src/**) -- Allow reads within the src directory
• mcp__* -- Match all MCP tools

Dangerous Action Detection

The app automatically detects risky operations and escalates them for your review:

• Destructive commands (deleting files, formatting disks)
• Credential access attempts (reading SSH keys, API tokens)
• Privilege escalation (using sudo, changing file ownership)

Safe operations like reading files and searching code proceed without interruption.

AI Safety Review (Optional)

An optional safety feature provides an independent AI-based review of sensitive tool calls. When enabled in settings, it adds a fast automated check before executing potentially risky tools. This runs in the background -- you won't see it unless the system flags a concern, which escalates to a permission dialog for your review.

Tool Lifecycle Hooks

For advanced automation, you can set up hooks that run before or after the agent uses any tool. Configure these in Settings > Hooks:

• Pre-Tool-Use -- Runs before execution. Can allow, deny, or modify the action. Useful for custom approval workflows or input sanitization.
• Post-Tool-Use -- Runs after execution. Useful for logging, auditing, or triggering follow-up actions.

Each hook can target specific tools using a pattern (e.g., Write|Edit for file modifications, Bash for shell commands). Four hook types are supported: shell command, HTTP webhook, prompt, or agent.

Sub-Agent Supervision

When an agent delegates work to sub-agents, you can monitor their progress in real-time:

• Sub-Agent Panel -- Shows all spawned sub-agents with their status (running, completed, failed)
• Live progress -- See duration and token usage for each sub-agent
• Cancel control -- Stop individual sub-agents without affecting the parent task
• Permission forwarding -- Sub-agent permission requests appear in the same dialog, so you maintain control over all actions

The panel appears automatically when sub-agents are active and hides when none are running.

Run Tree

The Run Tree gives you a persistent, hierarchical view of every agent run associated with a task — including sub-runs spawned by delegation. Unlike the live sub-agent panel, the run tree is preserved across page refreshes so you can review the full execution history even after a task completes.

Each entry in the tree shows:

• Provider and model used for that run
• Status — running (amber), completed (green), failed (red)
• Cost and token usage (input/output tokens)
• Error details when a run fails (expand the row to read the error)

A summary header at the top of the tree shows totals across all runs: combined cost, total tokens, and how many runs are currently active. Click any row to expand or collapse its details. Nested runs are indented to show the delegation chain.

Session Safety

The session safety system protects against runaway costs and agent loops:

Cost Cap

• Maximum session cost: Configurable limit (default: $10 per session)
• Tracks cumulative cost across all tool calls in a session
• Blocks further execution when the cap is reached

Loop Detection

• Tool call rate limit: Maximum calls per minute (default: 20)
• Detects when an agent is stuck in a repetitive loop
• Alerts you when the threshold is exceeded

Configure these in Settings > Usage > Safety tab.

Conversation History

For long-running sessions, the app manages conversation history automatically:

• Keeps the conversation within context limits
• Important facts are captured to long-term memory before older messages are trimmed
• You can continue working seamlessly even in very long sessions

Learn More

• MCP and Skills -- Extending agent tool access
• Memory System -- How agents remember across sessions
• Workspace Security -- How agent actions are sandboxed
• Projects -- Organizing tasks into projects