Documentation / 1.14.1
Use Toskar in the terminal
Chat with Toskar in a terminal, hand it files and command output, have it work in a folder, and point a coding agent at its models.
toskarctl chat holds a conversation with Toskar in any terminal, on this computer or over SSH. It's one of your chats, so it shows in History in the apps, and a chat begun on your phone continues here.
Asked to do something in a folder, such as fixing a failing test, it works step by step and asks before it changes anything. toskarctl connect points a coding agent, such as Claude Code or Codex, at a model on Toskar.
What you need
- Toskar on this computer. If it isn't running,
toskarctl chatstarts it, and if it isn't installed, it offers to install it (Install Toskar). - A model. When there's none,
chatnames the one that suits this computer, with its size, and installs it if you say yes (Models). - For Toskar on another computer: its address and an API key (The API).
Chat
- Open a terminal.
- Run
toskarctl chat. - Type a message and press Return. The answer shows as it's written, and ends with its speed.
- Type
/exitor press Ctrl-D to leave. The chat stays in History.
With a message after chat, it answers that and leaves, then prints the command that continues the chat:
toskarctl chat "Plan a three-day trip to Juneau"You’ll see something like:
…Juneau…
Continue this chat: toskarctl chat --resume …| While chatting | What it does |
|---|---|
/new | Starts a new chat, in the same project |
/model id | Changes the model for the next message, or auto to let Toskar choose |
/profile id | Answers as another profile (Profiles) |
/attach path | Sends a file as data with the next message |
/project name | Moves this chat into one of your projects, or none to take it out. Alone, /project says which project the chat is in |
/swarm | Sends the next message to a swarm of agents. /swarm race sends it to a race, and /swarm off stops what --swarm asked for |
/agents | Lists the last swarm's agents: each one's part, how it did, and its chat |
/open N | Continues agent N's chat here. /back returns to the swarm's chat |
/log | Shows what ran in this chat, its result, and who allowed it |
/help | Lists these |
/exit or Ctrl-D | Leaves |
toskarctl chat --resume lists your 10 most recent chats to pick from, including ones from the apps. --resume with a chat's id continues that one. --model and --profile choose who answers from the start.
Chat in a project
A project keeps related chats together with their instructions, files, and memory (Projects). Make and change projects in the web or desktop app. toskarctl projects lists yours, with how many chats are in each.
- Run
toskarctl projectsto see your projects' names. - Run
toskarctl chat --project "Kitchen remodel", with your project's name. Upper and lower case don't matter. - Chat as usual. The answers follow the project's instructions and search its files.
With --resume, chat --project lists only the project's chats. When two of your projects share a name, use the id that toskarctl projects shows. In a chat, /project says which project it's in, /project with a name moves the chat there, and /project none takes it out.
On the computer Toskar runs on, a project's chat still works in the folder you started chat in, even when the project has a folder of its own. So a project for your code works from wherever you are.
Hand it a file or a command's output
--file sends a file as data with the first message. Toskar sends it as something to work on, and tells the model to follow your message, not instructions inside the file.
printf 'Buy milk\nCall the dentist\n' > notes.md
toskarctl chat --file notes.md "Turn these into a to-do list"You’ll see something like:
…
Continue this chat: toskarctl chat --resume …Pipe a command's output into chat to ask about it. It answers once, with what you piped as the data:
printf 'FAIL: TestSum: got 7, want 9\n' | toskarctl chat "Why did this fail?"You’ll see something like:
…
Continue this chat: toskarctl chat --resume …Have it work in a folder
chat works in the folder you start it in, on the computer Toskar runs on. Commands run there, and its file tools reach only that folder. It follows the project's notes in AGENTS.md, TOSKAR.md, or CLAUDE.md, the first one it finds.
Ask it to do something rather than ask a question, such as "Fix the failing test" or "Set up this project", and it works step by step. It runs something, reads the result, fixes what failed, and tries again. It stops when it's finished, when the same step keeps giving the same result, or after 100 steps. Then it says what it did and what's left.
Here is a real session, recorded with Qwen 3.5 9B in a small Go project whose test fails. Toskar looked around, read the code, found the bug, and asked before changing the file. The answer here was n, so nothing changed:
› Fix the failing test
I need to see the failing test and the project structure to help fix it. Let me start by exploring the workspace to find the test files and understand the current state of the codebase.
· Looking for *test*
The search returned no matches, which is strange. Let me check the git status to see if there are any modified files, including tests, and also list the files in the current directory to understand the structure.
· Checking what changed
It seems the workspace is not a git repository. Let me list the files in the current directory to find the test files and understand the project structure.
· Looking for .
I found three files: `go.mod`, `tally.go`, and `tally_test.go`. Let me read the test file first to see what's failing.
· Reading tally_test.go
Now let me read the implementation file `tally.go` to see what the `Sum` function currently does.
· Reading tally.go
The test is failing because the `Sum` function in `tally.go` skips the first element of the slice. It starts the loop at `i := 1` instead of `i := 0`, so it never adds `nums[0]` to the total.
**The Fix:**
Change `for i := 1;` to `for i := 0;` in `tally.go` to include the first element.
Toskar wants to run filesystem.write:
{
"content": "package tally\n\n// Sum adds up the numbers.\nfunc Sum(nums []int) int {\n\ttotal := 0\n\tfor i := 0; i \u003c len(nums); i++ {\n\t\ttotal += nums[i]\n\t}\n\treturn total\n}\n",
"path": "tally.go"
}
Allow? [y]es, [n]o, [a]lways in this chat: n
I identified the issue in `tally.go`: the loop starts at index 1 instead of 0, skipping the first number. I attempted to fix it by updating the code, but you declined the change. To fix the test, you need to change `for i := 1;` to `for i := 0;` in `tally.go`.
37 tokens/s
› /exitWhat asks first
- Reading inside the project, and running known tests and builds such as
go testornpm test, don't ask. - Changes ask: writing a file,
git commit, installs,make, andnpm run, which run whatever the project says. - When it asks, it shows the exact command. Type
yto run it once,nto say no, orato let that tool run for the rest of this chat. - A command that can't be undone, such as
rm,sudo, orgit push --force, asks every time, andaisn't offered for it.
Warning: Tests and builds run the project's own code. Don't start a task in a project you don't trust, and choose a only for one you do.
Toskar keeps its own record of which checks ran and how they ended. When the last test failed, or a change came after it, the model goes back once to deal with it. Anything still in doubt shows under the answer as "Toskar noticed". The model matters most here: small models often can't finish a task, and chat says which model would do better.
Use a swarm
A swarm has several agents work on your message at once, each in a chat of its own, and the answer is written from what they did (Swarms). toskarctl chat --swarm sends every message in the chat to one, and /swarm sends just the next. In a split, the default, the job is split into parts; --swarm race has each of the profile's swarm models do the whole job, and the best result is kept.
- Open a terminal in your project's folder.
- Run
toskarctl chat --swarm. - Ask for the work, such as "Fix the failing test and add a test for Max".
- Watch the agents. Each has one line, updated as it works: its part, computer, model, how it's doing, and its latest step.
- Answer an agent's question about a tool as usual. It says which agent asks, and
aallows that tool for that agent alone. - Read the answer. For work in a folder, the line above it says the branch with the change, whether the project's tests passed, and whether the change is in your folder.
Work in a folder needs an Admin, as a folder does. When the change isn't in your folder, run git merge with the branch it names. Ctrl-C stops the whole swarm. With one model on one computer, a swarm runs as one agent, and the line under the answer says why:
toskarctl chat --swarm race "Plan a three-day trip to Juneau"You’ll see something like:
…Juneau…
One agent: a race needs at least two models to compare.
Continue this chat: toskarctl chat --resume …Afterwards, /agents lists the agents with their part, how each did, and its chat id. /open 2 continues agent 2's chat right there, to ask it more, and /back returns to the swarm's chat. When the output isn't a terminal, each change is a plain line on standard error instead, so a pipe still gets only the answer.
Use Toskar on another computer
Set TOSKAR_URL to the other computer's address and TOSKAR_API_KEY to an API key, then run toskarctl chat as usual. This works over SSH too, with no screen needed. Commands and files are then on the Toskar computer, not this one, and an approval says which computer a command runs on.
Connect a coding agent
A coding agent such as Claude Code or Codex can use a model on Toskar directly, with the agent's own tools. toskarctl connect prints the settings it needs: the address, a key, and the model. Add --write to save them where the agent reads them, without changing its other settings. A step-by-step guide ↗ covers Claude Code and Codex, on this computer and from another one.
toskarctl connect claude-codeYou’ll see something like:
# Claude Code with … on Toskar, through Anthropic's Messages format.
# Set these, then run claude; or write them for this folder: toskarctl connect claude-code --write
export ANTHROPIC_BASE_URL=http://127.0.0.1:…
export ANTHROPIC_AUTH_TOKEN=toskar-local
export ANTHROPIC_MODEL=…
export ANTHROPIC_DEFAULT_OPUS_MODEL=…
export ANTHROPIC_DEFAULT_SONNET_MODEL=…
export ANTHROPIC_DEFAULT_HAIKU_MODEL=…toskarctl connect codexYou’ll see something like:
# Codex CLI with … on Toskar, through OpenAI's Responses format.
…
[model_providers.toskar]
…
wire_api = "responses"
…
model_provider = "toskar"| Agent | What --write saves |
|---|---|
claude-code | .claude/settings.local.json in this folder, which Claude Code keeps out of Git |
codex | A toskar provider in ~/.codex/config.toml, and a toskar profile beside it. Run codex --profile toskar, and your default stays as it was |
opencode | A toskar provider in opencode.json in this folder |
aider | Nothing: put the printed lines in your shell profile |
Without --model, connect picks the best installed model for an agent: one that calls tools, then one made for code, then one that fits this computer well. On this computer no key is needed, so agents get the stand-in toskar-local. For another computer, the key needs raw access, "Drive models directly, for coding agents" in API Access.
Tip: For an editor's own AI features, such as Continue, Cline, Zed, or Copilot Chat, toskarctl connect continue and the like print what to enter in its settings. For Continue, a step-by-step guide ↗ covers it. In VS Code, the Toskar extension sets this up for you (Use Toskar in VS Code).
Run a coding agent's subagents at once
Claude Code starts subagents for parts of a job, often several at the same time. With one model on one computer, they wait for each other. --swarm points the subagents at a profile's swarm instead: each of their requests goes to the least busy of the profile's swarm models and computers, so they run at once (Swarms). The agent's own model stays as it was.
toskarctl connect claude-code --swarm general-assistantYou’ll see something like:
# Claude Code with … on Toskar, through Anthropic's Messages format.
# Its subagents use swarm:general-assistant: those it starts at once run at once, across that profile's models and computers.
…
export CLAUDE_CODE_SUBAGENT_MODEL=swarm:general-assistant- In Profiles & Orchestration, edit the profile and open Strategy and computers. Set Strategy to Swarm, and choose its models in order. Choose models on different computers, or more than one model, so requests can run at the same time.
- Run
toskarctl connect claude-code --swarmand the profile's id, or its name with dashes between the words, such ascoding-swarmfor Coding swarm. Add--writeto save it. - Start Claude Code and give it a job that needs several subagents. Each subagent's request runs on whichever computer and model is free.
Any agent that speaks OpenAI's or Anthropic's format can use swarm: and a profile's id as its model (Use the API). A request that brings the agent's own tools, as subagents' always do, goes as it is to the least busy computer and model, and its answer comes back unchanged. A request without tools runs a whole swarm on its last message, and answers with the swarm's answer, with the agents' progress as its reasoning. So keep swarm: for subagents, not for an agent's quick background requests, such as naming a chat.
Tip: Agents' requests with their own tools need a key with raw access, as for the agent's own model. A whole swarm needs a Member or an Admin, and saves its chats in a project named after the job.
Troubleshooting
| What you see | What to do |
|---|---|
| "Toskar has no model yet" | Say yes to the model chat suggests, or install one in Models |
| "Starting its service here needs an administrator" | Run the command it gives, such as sudo systemctl start toskar, then try again |
A tool that asks first doesn't run when you pipe into chat | Nobody can answer the question then. Run chat without a pipe to approve it |
toskarctl can't reach Toskar on another computer | Check TOSKAR_URL and TOSKAR_API_KEY, or unset them to use Toskar on this computer |
| A task stops without finishing | Read what it says is left, and try a larger model with /model |
These pages describe Toskar 1.14.1. Download 1.14.1 and its release notes ↗ · Need help? Report a bug or request a feature ↗