Skip to main content

​
Troubleshooting

Start with:

​
No events appear

  1. Run termyte init again.
  2. Restart the selected coding agent.
  3. Complete a task that uses at least one tool.
  4. Confirm the agent process sees the same TERMYTE_HOME and TERMYTE_DB values as your terminal.
  5. Inspect sessions and diagnostics in the Viewer.
For OpenCode, confirm that both ~/.config/opencode/plugins/termyte.js and its entry in opencode.json exist. doctor does not currently check OpenCode.

​
Hooks are partial or missing

termyte doctor lists missing Claude Code and Codex hook events. Re-run setup after upgrading Termyte or moving Node:

​
Background work is stuck

Open the Viewer diagnostics. Check pending, leased, failed, and dead jobs. The worker uses leases and retries; dead jobs need operator attention. If automatic worker startup was disabled with TERMYTE_AUTO_WORKER=0, run the installed termyte-worker binary yourself.

​
Task update reports a version conflict

Another process changed the task first. Run termyte task show --task <task-id>, read the new version, and retry only after reviewing the newer state.

​
A step cannot be verified

Use the current task version and include --confirm yes. The task service will not accept agent-authored verification or missing passing evidence.

​
Resume shows unexpected drift

Check the current branch, commit, modified paths, deleted paths, untracked files, and merge conflicts. Create a new checkpoint only after deciding that the current checkout is the state you want to preserve.

​
The first retrieval is slow

The local embedding model may be downloading and loading. Keyword retrieval remains available when embeddings cannot initialize.

​
Expected context is missing

Termyte may reject stored context when a referenced file changed, disappeared, or points outside the current workspace. Check the current Git status and inspect the context packet in the Viewer. If Git or the workspace cannot be checked, the result is marked unverifiable instead of current.

​
Session processing failed

Open Viewer diagnostics and look for a failed or dead consolidate_session job. The worker retries temporary failures. A dead job remains visible for operator review.

​
Resetting data

Termyte has no public delete command. Stop agents, the Viewer, MCP clients, and workers before manually removing the configured database and its adjacent WAL files. This permanently removes the local corpus.