What do I need before running my first task?
You need Tallos installed, one agent CLI that is installed and signed in, and a git repository on your machine. If you have not installed Tallos yet, follow the macOS or Windows guide. If no agent is connected, open Settings → Connections and follow how to connect your agents.
- Tallos on macOS 13+ or Windows 10+.
- One connected agent, for example Claude Code, Codex or Gemini CLI.
- A git repository with a clean main branch. A side project is a good first target.
- A small, checkable task. A bug fix, a test, or a tiny UI change you can verify in minutes.
How do I run my first task in Tallos, step by step?
- 1
Finish the welcome
On first launch, pick your language and your default agent under Which AI agent do you use?, then click Continue. Leave Let agents run commands without asking off under Advanced for now: the agent will ask before running commands.
- 2
Open a project
Click Choose a folder and pick your repository, or Clone from a URL. Tallos reads the repo's git state and uses your default branch as the base every new workspace starts from.
- 3
Start a task in its own workspace
Click New workspace in the sidebar, or the + next to your project. A short tour points at the three fields: Project, a task name (leave it blank and Tallos names it from your first message) and Agent. Create it. Tallos runs
git worktree addin the background and shows progress in the new tab. - 4
Describe what you need
Supported agents such as Claude Code and Codex open in a clean chat by default. Type the task in plain words: what to change, where, and how you will know it works. Agents without chat support open straight in the terminal.
- 5
Watch the agent work
Follow progress in the chat, or click View terminal in the pane header to see the raw CLI. The sidebar shows which workspaces are working and which need you. Answer permission prompts as they come.
- 6
Try a second agent (optional)
When the tour Try a second agent appears, click Try another agent. Tallos gives the same task to another agent in another copy of your project, so you can compare two results side by side.
- 7
Review the changes
When the agent finishes, click Review changes. You see every change against the branch the workspace started from. Leave notes on specific lines and use Send notes to to hand them back to the agent in one batch.
- 8
Keep or discard
To keep the work, stage and commit in Source Control, push, then Create PR. To discard it, right-click the workspace and delete it; Tallos confirms, then removes the folder and its branch. Your main checkout never changed either way.
Ready to try the loop on your own repo? Get Tallos.
What is a workspace in Tallos?
A workspace in Tallos is a separate on-disk copy of your repository, created with git worktree, with its own branch, its own files and its own agent sessions. That is why the tour says your original stays safe: the agent edits the copy, never your main checkout. It is also why two agents can work at once without touching each other's files. The git worktrees guide explains the mechanism.
Agent in your main checkout
- Edits land in the folder you are working in
- A second agent means file conflicts
- Undo means
git stashorgit reset
Agent in a Tallos workspace
- Edits land in a separate worktree and branch
- Each agent gets its own copy
- Discard means deleting the workspace
What makes a good first task for an AI agent?
A good first task is small, specific and easy to check. You are learning the loop, not stress-testing the agent. Name the file or feature, state the expected behavior and say how to verify it.
| Task type | Example prompt | How you verify |
|---|---|---|
| Bug fix | “The date on the invoice page shows UTC. Show it in the user's timezone.” | Open the page and compare |
| Test | “Add unit tests for parsePrice covering empty strings and commas.” | Run the test command |
| Small UI change | “Add a loading spinner to the Save button in SettingsForm.” | Click Save and watch |
| Refactor | “Extract the retry logic in api.ts into a helper. No behavior change.” | Tests still pass; diff is contained |
How do I decide whether to keep an agent's work?
Keep the work only when the diff does what you asked and nothing else. Read every file, run the tests, and check for changes outside the task. If something is close but wrong, annotate the lines and send the notes back instead of fixing it yourself. The full checklist is in how to review AI-generated code, and the diff review feature covers every tool in the review pane.
Troubleshooting: what if my first task gets stuck?
- Creating the workspace fails. The base branch may not be fetched. Run
git fetch originin the project, or choose another branch to start from. - The agent does not start. Run its CLI (
claude,codex,gemini…) in a terminal. If it fails there, reinstall or sign in again from Settings → Connections. - The agent waits forever. It is probably asking for permission. Open the chat or click View terminal and answer.
- Tests or the dev server fail in the workspace. A new worktree has no gitignored files, such as
node_modulesor.env. Install dependencies in the workspace, or list the files in a.worktreeincludefile at the repo root so Tallos copies them into new workspaces. - You cannot find the review. Click Review changes in the tour, or open Source Control in the right sidebar of the workspace.
What should I try after my first task?
Run the same task on two agents and compare the diffs, then read how to run AI agents in parallel. When you want a leader agent to split and supervise the work for you, move on to your first squad.
Try it on your own repo.
Frequently asked questions
Does Tallos change my main branch when an agent works?
No. Each task runs in its own workspace, a separate git worktree with its own branch. Your main checkout only changes when you merge the work yourself.
Can I talk to the agent in a chat instead of a terminal?
Yes. Supported agents open in a chat by default, and View terminal in the pane header switches to the raw CLI. You can make the terminal the default under Settings → Agents → Agent View.
How do I undo everything an agent did?
Delete the workspace. Tallos asks for confirmation, then removes the worktree folder and its branch; your main checkout is untouched.
Do I have to name every task?
No. Leave the name blank and Tallos names the workspace from your first message.
Can two agents work on the same task at the same time?
Yes. Use Try another agent or create a second workspace with a different agent. Each gets its own copy of the project, so you can compare results.
Why does the agent keep asking for permission?
Permission bypass is off by default in Tallos, so agents ask before running commands. You can change this under Settings → Agents → Agent Permissions once you trust the agent and the task.
