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 reference 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
Build	Default — 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

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.

Ralph Mode in Detail

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

1. The agent creates a todo checklist from your request.
2. It works through each item, marking them done as it completes them.
3. After finishing all items (or reaching the maximum turn count), it stops and reports what it did.

You can adjust the turn limit in Settings > General > Maximum Turn Count. The agent uses the todo tool to track progress, so you can see which steps are complete and which remain.

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)

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)
code_search	Full-text search (FTS5/BM25) + regex across the codebase (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
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.

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.

Code Search

The code_search tool lets the agent search the entire codebase using full-text search (FTS5 with BM25 ranking), regular expressions, or file path patterns. It supports:

• Token search — find identifiers, class names, or function names across all files
• Regex patterns — search with regular expressions (e.g. function\s+\w+\s*\()
• File path filtering — restrict results by glob patterns (e.g. **/*.ts)
• Pagination — handles large result sets with offset/limit controls

The code search index is built automatically when the agent first uses it in a thread.

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.

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 will be prompted to download a small speech recognition model (~75 MB). The model is cached locally so it only needs to be downloaded 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 entirely in your browser using WebAssembly — no audio data is sent to external servers. Choose the voice model in General Settings.

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