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 (hammer icon) to the left of the input field to choose how the agent behaves:

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
Ralph	Autonomous iterative loop — the agent works through a todo list, automatically continuing until all items are complete or the iteration limit is reached
Orchestrate	Plans on a smart model (or your current chat model) and delegates implementation to the project’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 Project Settings → Advanced → Model Aliases; projects without either 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. Ralph mode is useful for multi-step features where you want the agent to keep going 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 Project Settings → Advanced → Model Aliases. If Cheap is not set, Tarsk shows a dialog with a link that opens those settings and scrolls to Model Aliases.

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.

Ralph Mode in Detail

Ralph mode runs the agent in an autonomous loop. When you send a message:

1. The agent creates todo stories from your request (todo tool — not tasks).
2. It implements one story per iteration, runs project quality checks, then marks the story verified with passes: true.
3. Tarsk clears conversation context and starts the next unfinished story (up to 10 iterations), carrying memory through git history, progress.txt learnings, and the todo list.
4. When every story has passes: true (or the iteration limit is hit), the loop stops.

Use Maximum Turn Count in settings to cap tool turns within a single iteration; the Ralph story loop itself stops after at most 10 iterations. With Smart JS enabled, todo and bash are invoked through run_js (callTool / bash(...)) because they are not direct tools.

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

The mode selector also includes a Confirm commands toggle when your project requires command approval. 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, Ralph 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 / 512 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	Fetch a URL and summarise or extract content from the page
run_js	Execute JavaScript in the Browser tab’s webview context
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
open_widget	Mount a WebMCP widget URL as an inline iframe in chat
call_widget_tool	Invoke a tool exposed by a mounted WebMCP widget
MCP tools	Tools provided by configured MCP servers (loaded on demand)

All file and shell operations are sandboxed to the thread’s directory. The agent cannot read or write files outside it. Bash commands and web fetches may require your approval — see Permissions.

Tool Output Compression

When the find or grep tools return more than 20 results, Tarsk automatically compresses 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.

Widgets: open_widget loads an external WebMCP page (document.modelContext tools) in the chat. call_widget_tool runs one of that page’s client-side tools. Use these when a skill or prompt points at a widget URL.

You can disable specific tools per project in Project Settings under Advanced → 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.

Both tools require an image-capable model to be enabled in Provider Settings. Check the Tools filter when browsing models to find ones that support image generation. Generated images can be saved or copied 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 for cross-iteration memory

Todos are per-conversation and help you see what the agent has completed and what remains. In Ralph mode, the agent uses todos to drive its autonomous iteration loop.

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.

User Tasks

User tasks are follow-up items you save for later without sending immediately:

1. Click the + menu in the chat input and choose Add to tasks, or use the tasks button in the toolbar.
2. Tasks appear in a pending list you can review and send when ready.
3. Useful for capturing ideas mid-conversation or queuing follow-ups for after the current agent run finishes.

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 chat header displays a daily spend counter when enabled. Toggle it in Settings → Settings → Daily 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 thread has an independently selected model. Click the model selector dropdown in the chat toolbar to change the model for the current thread without affecting other threads. 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