Troubleshooting
What you see, why it happens, and the exact key or command that fixes it.
Find what you see on screen. Each entry gives the cause in one line, then the fix.
Stuck on something not listed here? Ask CodeAF in plain words, such as "what keys open the wall?". It looks the answer up in its own manual, which ships inside it. See the FAQ.
Find your symptom
Install and version
Installing, updating, and which build you run.
the docs can run slightly ahead of the stable release.
check which build you run:
codeaf version
codeaf v0.4.1 is stable. A tag that starts dev- is dev, and staging- is staging. To get the newest dev build beside your stable one, run:
curl -fsSL https://agentfield.ai/get/devaf | bash
Then start it with devaf in place of codeaf. To switch your codeaf itself to dev, run codeaf update --dev, or type /update dev in a chat. To go back, run codeaf update --stable. Once on dev, a plain codeaf update keeps you on the newest dev build.
You can also build dev from source. It needs Go 1.26 or newer:
git clone --branch dev https://github.com/Agent-Field/codeaf.git
cd codeaf && make build
Then run bin/codeaf from that folder.
the install folder, ~/.codeaf/bin, is not on your PATH yet.
the installer prints an export PATH=... line as the last thing it says. Paste it into your shell, or open a new terminal.
there is no release build for this system. Builds exist for macOS, Linux and Windows, on x86-64 and ARM.
build from source with make build, as above.
GitHub limits how often one address may ask for releases, or there is no network.
wait a few minutes, or set GITHUB_TOKEN and run the install line again. To pin one release, end the line with | VERSION=<tag> bash.
a build you made yourself cannot update itself from a release.
run make build again in your checkout, or install a release with curl -fsSL https://agentfield.ai/get/codeaf | bash.
chat options go after the word chat.
codeaf chat --model <slug>. codeaf --help lists every verb.
Getting started
Keys, models and the first minutes in a chat.
CodeAF found no model service key.
run codeaf connect openrouter to sign in with your browser, or export OPENROUTER_API_KEY and start again.
the account behind the key has no credit left.
add credit at the link in the message, or pick another model with /model.
the service rejected the key, or its check got no answer.
run codeaf connect <service> again with a valid key.
no provider serves that model today.
pick another with /model. In the picker, Ctrl+R refreshes today's list.
the provider is slow to reply.
wait, or switch models with /model.
choosing /task from the / list puts /task in the box. Anything you type next becomes the task's brief.
press Enter a second time to open the task page, or clear the box with Ctrl+U before you type something else. If a task started by mistake, press X in its room, then 1 and Enter.
this is by design. The engine keeps conversations and tasks going with no window open.
see what runs with codeaf engine --status-all. Stop everything with codeaf engine --stop-all.
Tasks and parallel work
Tasks that wait, merge, conflict or do not start.
the machine is busy. When the load is above 1.5 per core, CodeAF starts no new task. Running tasks are not touched. On a laptop this is rare; on a shared build server it is common.
open /settings, go to Tasks, and set busy machine higher, or to 0 to stop watching the load (this is the task.max_load setting). Then run codeaf engine --stop-all and open CodeAF again, so the waiting task picks up the new value.
while a card counts down, the first key only stops the clock. The pointer can still be on 1 start it.
look at the pointer before you press Enter. If it is not on your answer, press your digit again.
your checkout is on a branch that tasks never merge into on their own, such as main or dev.
merge the kept task/... branch yourself, or work from a feature branch.
the task's branch did not merge cleanly.
open the task and choose to resolve it, or drop it.
another CodeAF window has work in the same repository.
let that work land first, or continue from that window.
the engine answered slowly, and the task did start.
check the task list with Ctrl+. before you start it again.
the task list still holds the keyboard, so Enter opens a task instead of sending.
press Alt+T to give the keyboard back to the box, then press Enter.
Teams and managers
Managers, hires, shared windows and team caps.
after Shift+M makes a manager, the keys stay on the page's rail. Letters run page keys: S opens the team's settings.
press Esc after Shift+M, then type your message to the manager.
a manager has no handle until it has answered once, so other managers cannot address it.
send every new manager one message first, such as You manage the product team. Reply ready. It gets a handle from that answer.
with a manager in front, Esc interrupts its running answer.
to reach the rail, press Alt+↑, then ↑ ↓ and Enter. Send the manager a message to carry on.
the hint is wrong. M is Move into.
press Shift+M to start a manager.
approvals start on YOLO, so a manager's hires need no answer from you.
in the manager's conversation, press Alt+A until it reads asks. Do this in each manager: one it starts does not take your choice with it.
another CodeAF window holds that conversation.
switch to that window, or start a new conversation here.
another CodeAF held the teams file for a moment.
make the change again. Undo is still offered.
the team spent its daily cap, so no new member work starts.
choose Raise on the card, or change the cap on the team's card: S on the teams rail.
Standing orders
Always-on rules, timers and background checks.
plain words can be kept as a memory note instead of a standing order.
say it with /standing <words>. A card comes; press 1 to set it up.
the standing page files it on the wrong shelf. The rule still applies in this project.
nothing to do. To stop it, open /standing, select it, press →, then S.
on dev today, the rules reach the chat but not the workers of a task.
put the rule in the task's brief as well.
timed orders are checked on a 5-minute pass. The card says so.
nothing to do. Choose a gap of 5 minutes or more.
the machine has no user session to hang a timer on, which is common over a plain ssh login.
the order is still kept, and it runs while a CodeAF window is open on that machine.
Remote machines
Working over ssh: installs, reconnects and engines.
CodeAF is not on the other machine, or not on the PATH a non-login ssh command sees.
install CodeAF there, then check with ssh <host> codeaf version. That machine needs its own model key too: run codeaf connect there.
the link dropped. CodeAF redials for five minutes, and the work keeps going on the other machine.
run the same codeaf chat --host ... again. The conversation is still there.
the window that reconnected did not get the keyboard back.
press Enter once.
CodeAF's home folder path is too long for the ssh link file it keeps there.
keep CodeAF's home at a short path. The default, ~/.codeaf, is fine; if you set CODEAF_HOME to a deep folder, choose a shorter one.
an engine from another build holds that folder.
run codeaf engine --stop --workspace <folder> on that machine, then connect again.
without --workspace, it checks your home folder, not the folder you are in.
use codeaf engine --status --workspace <folder>, or codeaf engine --status-all.
Spend
Task, crew, conversation and day limits.
each task may spend $5 unless you change it.
/crew cap task 10.
the crews reached the daily cap you set in /crew.
/crew cap <dollars>, or /crew cap off, or wait for midnight.
this conversation reached its own limit.
/budget conversation <amount> raises it, and /budget conversation none removes it.
on dev today, the day limit holds codeaf do and standing orders, but not chat turns.
set a limit that chats obey: /budget conversation 5.
codeaf do reached the day's limit.
raise it with /budget <amount>, or add --yes-spend to spend past it for one run.