Chat

The Chat view is where you interact with the AI agent. It occupies the main area of every thread. The agent can read and write files, run shell commands, search the codebase, fetch web pages, and ask you questions — all scoped to the thread’s isolated directory.

Sending Messages

Type in the chat input at the bottom of the screen and press Enter to send. Use Shift+Enter for a new line.

File References

Type @ in the input to open an autocomplete dropdown of files in the thread’s directory. Select a file to insert a path like src/components/Button.tsx. The agent will read that file as context for your message.

Attachments

Click the + button in the chat input to attach files to your message. Attachments are sent alongside your prompt so the agent can analyze images, documents, or other files you provide.

Slash Commands and Skills

Type / to autocomplete slash commands — reusable prompt templates stored in .agents/commands/. Skill names can also appear in autocomplete when relevant.

Message Queue

If the agent is still processing a previous message when you send a new one, the new message is queued and sent automatically when the current response completes. A queue indicator appears in the input area. This lets you compose follow-up messages without waiting.

Chat Modes

Use the mode selector to the left of the input field to choose how the agent behaves. The button shows the icon of the current mode:

Mode	Behaviour
Auto	Default — picks the model for a thread’s first prompt (Cheap, Smart, or your current model) using the project’s Fast model, or Cheap when Fast is unset
Build	The agent reads, writes, and runs commands to implement your request
Plan	The agent produces a structured plan without making changes
Image	Focuses on image generation and editing tasks
Orchestrate	Plans on a smart model (or your current chat model) and delegates implementation to Tarsk’s Cheap model via subagents

Auto mode chooses the model, never the mode: it always runs as Build. It is the default when a Fast or Cheap model alias is configured under Settings → Providers → Default Models; without either alias, projects start in Build mode. On a thread’s first prompt, Tarsk asks that model — Fast when it is set, otherwise Cheap — to classify the prompt as Cheap, Smart, or Default, and the matching alias (or your current model, for Default) becomes the thread’s model. Later prompts in the thread skip the classification and run on that model, which you can change in the model selector at any time. Your prompt moves into the conversation as soon as you send it and the agent shows Picking a model… until the classification comes back; if it fails, the prompt is returned to the chat input so you can send again or pick a model yourself. The model selector is hidden until the first prompt is sent, since Auto is choosing that model. Hover the mode selector to see which model Auto decides with and which Cheap and Smart models it can pick from.

The mode you pick is remembered for the project: new threads and project switches start in it, and it persists across restarts. Auto is the default until you choose something else. Plan mode is useful for understanding scope before committing to changes. A Goal, started with /goal, is useful for a long-lived objective you want the agent to carry across Rounds without manual follow-ups. Orchestrate mode is useful when you want a capable model to break work down and a cheaper model to implement each step.

Orchestrate Mode in Detail

Orchestrate is always available in the mode selector. Selecting it (or using /orchestrate) requires a Cheap model alias under Settings → Providers → Default Models. If Cheap is not set, Tarsk shows a dialog with a link that opens those settings.

When Orchestrate is active:

1. The prompt includes /orchestrate.
2. The main agent runs read-only: it explores the codebase, creates small todo items, and spawns subagents — it does not edit files itself.
3. If a Smart alias is configured, the orchestrator uses that model; otherwise it uses the current chat model.
4. Every subagent is forced onto the Cheap alias with the full Build tool set.

Goals in Detail

A Goal is a long-lived objective that Tarsk works toward until an independent verifier accepts a Round’s evidence. Start one by sending /goal <objective> — for example, /goal Add password reset to the account area.

You can name a command to run as evidence: /goal Add password reset --check "bun test -t auth" (quote a command that contains spaces). /goal … --rounds <n> caps the Rounds (100 at most) and /goal … --spend <usd> caps the spend. The Goal panel shows the objective and each Round. It does not show a check to set. A command the agent records itself has to be a single command a script runner can take — no pipes, redirects, or || true — so the exit status is the command’s own. That status is evidence the verifier reads. A pass does not finish the Goal. /ralph <objective> is the older name for the same command.

A Goal runs in Rounds:

1. Before the first Round changes anything, a read-only verifier decides whether the objective can be recognized as done. If it cannot, the Goal parks and tells you, and no Round runs.
2. The working Round does the work and finishes by writing an Evidence section: what changed, which commands ran, and what they printed. It does not declare the Goal complete. If you named a command, the Round runs that command exactly and includes its exit status.
3. Every Round after the first begins with an empty context window, cleared in place inside the same conversation. The agent keeps continuity through the project files, Git history, and the todo list, so anything the next Round needs must live in the repository.
4. After the Round, a separate read-only verifier reads the evidence and decides whether the Goal is complete or another Round is needed. If it reaches the round cap (100 by default) first, it pauses for you — a Goal never resumes itself. A Round that ends in an error parks the Goal the same way instead of spending the rest of its cap.

While a Goal runs, the Goal button above the chat input shows its status, working time, and Rounds, and lets you Resume or End it. Todos are optional progress bookkeeping for a Round, not a precondition: a Goal with no todos is valid.

Use Maximum Turn Count in settings to cap agent tool-call rounds per response; the Goal itself runs for at most 100 Rounds unless --rounds sets a lower cap, and never more than 100.

A Goal is designed for well-defined, sizeable tasks: “Add a login page with email/password, form validation, and error handling” works better than vague prompts like “improve the app.”

Control Confirm Commands from General Settings. See Permissions.

Streaming Responses

Agent responses stream in real time. You can read the response as it’s being generated. The chat area shows:

• Text responses — rendered as Markdown (code blocks, headers, lists, inline code, Mermaid diagrams, etc.)
• Tool call indicators — inline status tags showing which tool the agent is using (e.g. read, write, bash, grep)
• Usage metadata — token count and estimated cost shown on completed messages
• ask_user blocks — if the agent needs clarification mid-run, it pauses and shows a question with a response input (see below)

Each response is labelled with the mode it ran in: Plan Agent, Image Agent, Orchestrator Agent, or plain Agent for Build. Auto runs as Build, so its responses are labelled Agent.

Agent Tools

The agent has access to these built-in tools:

Tool	What it does
read	Read a file (up to 2000 lines / 50 KB)
write	Write or create a file (creates parent directories)
edit	Exact find-and-replace within a file
bash	Run a shell command in the thread directory
grep	Regex search across files (powered by ripgrep)
find	Find files by glob pattern (ignores node_modules, .git)
ls	List directory contents (disabled by default)
fetch	Fetch a URL and return its content (may require approval)
web_search	Search the web for documentation, examples, and references
browser	Navigate and interact with the in-app browser, inspect pages, take screenshots, or call page-provided WebMCP tools
run_js	Orchestrate tool calls from small JS scripts in a sandboxed JS realm on the agent
generate_image	Generate an image from a text prompt and save it to a file
find_images	Search for a stock image matching a query
todo	Manage a task checklist to track work progress
tasks	Manage project-level Tasks view items (Plan, Build, etc.)
execute_skill_script	Run a script from an active skill’s scripts/ directory
read_skill_reference	Read a file from an active skill’s references/ directory
agent	Delegate work to a specialized subagent
tool_search	Discover and activate deferred tools (MCP, optional tools)
ask_user	Pause and ask you a question before continuing
get_observation	Retrieve full stored tool output by observation ID
MCP tools	Tools provided by configured MCP servers (loaded on demand)

Built-in file tools validate paths against the thread’s directory. Bash starts in that directory, but this does not confine shell commands to it. Enable the macOS Sandbox setting to restrict shell access. Bash commands and web fetches may require your approval; see Permissions.

Tool Output Compression

When the find or grep tools return two or more results, Tarsk may compress the output by grouping file paths by directory:

[Grouped by directory as "dir/: file1, file2". Each entry is a file at "dir/name".]
src/components/: Button.tsx, Header.tsx, Footer.tsx
src/hooks/: use-auth.ts, use-theme.ts

This reduces the number of tokens the agent consumes on large result sets. The grouped format preserves every file path and loses no information. Compression only applies when grouping produces a smaller output than the flat listing. The daily spend widget tracks how many bytes this saves.

Large tool results may be stored as observations. The agent calls get_observation with an ID from a preview to page through the full output.

You can disable specific tools per project in Project Settings under Plugins → Tools. Disabled tools are hidden from the agent in all threads for that project.

Image Generation

The generate_image tool lets the agent create images from text prompts using your configured image models (e.g. DALL-E 3, GPT Image 1). The generated image is saved directly to a file in the project. If no image models are enabled, the tool falls back to searching for a stock image instead.

When the agent needs to show media in the conversation area, it should return the resulting file path or URL plainly in its response. The chat UI renders supported image, audio, and video files inline when it receives a direct path or URL to them.

The find_images tool searches for stock photos matching a query and can also save them to the project. Use this when you need an existing image rather than a generated one.

Enable an image model in the provider’s Image tab in Provider Settings to generate images. Stock image search, including the fallback, does not require an image model. You can save or copy generated images from the chat UI.

Todo Checklist

The todo tool lets the agent manage a task checklist within the conversation. The agent uses it to:

• Break down complex tasks into discrete steps
• Track progress as it works (pending, working, done)
• Record learnings and discoveries that later Rounds can reuse

Todos are per-conversation and help you see what the agent has completed and what remains. In a Goal, todos are optional progress bookkeeping for the current Round — the Goal runs whether or not you keep a todo list.

Ask User (Mid-Run Questions)

When the agent encounters an ambiguous decision, it can use the ask_user tool to pause and show you a question:

“Should I replace the entire auth module or just add the new endpoint alongside the existing one?”

An input block appears in the chat. Type your answer and press Enter to let the agent continue. This keeps you in the loop on consequential decisions without interrupting trivial steps.

Compact Conversation

Type /compact to summarize the current conversation and reduce context size. Tarsk compacts older messages while preserving recent context, helping you stay within model token limits on long sessions.

Daily Spend Widget

The sidebar footer displays a daily spend counter when enabled. In the VS Code embed, the counter appears in the chat header instead. Toggle it in Settings → Settings → Spend.

Hover the counter to see a tooltip with:

• Today’s total spend
• Last 30 days total spend
• Average daily spend

Click the counter to open a detailed dialog that also shows:

• Token counts (input/output) for today and the last 30 days
• Tool output compression savings (bytes saved by automatic result compression)
• Prompt-cache reads and writes, including the cache hit rate

The counter refreshes each time an agent response completes. It tracks all AI usage across every thread: chat completions, git operations, and voice transcriptions.

Model Selector

Each chat has an independently selected model. Click the model selector dropdown in the chat toolbar to change the model for the current chat. The choice is saved per chat, so switching to another chat in the side panel — or opening another chat in the same workspace — shows that chat’s own model instead of the one you just picked. Models are grouped by provider with logos.

Only models that have been enabled in Providers & Models settings appear here. See Providers Overview for the full list of available providers and models.

Speech Input

The chat input includes a microphone button for voice-to-text. On first use, you download a local speech recognition model (~40 MB). The model is cached so it only downloads once.

Click the microphone button to start recording, then click it again (or the stop button) to stop and transcribe. The transcribed text is inserted into the input field.

Speech recognition runs in your browser via WebAssembly. No audio leaves your machine. Optionally enable AI Voice Cleanup in General Settings to strip filler words from the transcript.

Stop Generation

Click Stop while the agent is responding to cancel the current generation. Partial output remains visible; you can send a follow-up message immediately.

New Conversation

Click New Chat in the chat toolbar to start a fresh conversation in the same thread. This generates a new conversation ID and clears the visible chat, but all previous messages are preserved in Conversation History.

Keyboard Shortcuts

Action	Shortcut
Send message	Enter
New line in input	Shift+Enter
Toggle sidebar	Cmd+B
Create thread	Cmd+Shift+T
Open model menu	Cmd+Shift+M
Open Git Ops menu	Cmd+Shift+B

Related

• Permissions — shell and web fetch approval
• Skills — extend the agent with custom tools
• Subagents — delegate to specialized agents
• Image Generation — image models and tools
• Tasks — project-level Tasks view the agent can manage