Background Tasks

For complex software development, the agent often needs to track long-running work and keep persistent background services (a dev server, a build watcher, test runners) alive while continuing the conversation loop. KnightCode handles this with two related pieces: a background-process registry and a durable task ledger.

Background Process Registry

When a real OS subprocess is spawned, KnightCode tracks it so it never leaks:

• Process Monitoring: A heartbeat runs every 5 seconds, checking that each registered process is still alive and pruning entries for any that have exited.
• Process State: Live process state is stored in .knightcode/processes.json inside your project directory. Background command output is not permanently persisted to disk.
• Auto-Cleanup: When KnightCode exits — via /exit or SIGTERM — all registered child processes are torn down (SIGTERM, or taskkill on Windows) to prevent orphans. Ctrl+C/SIGINT is intentionally suppressed so it cannot accidentally kill the app or its tasks.

Task Tool Suite

Separately, the agent has a suite of tools for durable, multi-session task tracking, persisted as a ledger at .knightcode/tasks.json in your project. These tools manage task records — the actual work is performed by other tools (e.g. Bash).

1. TaskCreate: Creates a durable task record and returns its task-id.
2. TaskList: Returns all tracked tasks with their current statuses.
3. TaskGet: Reads the details of a specific task by ID.
4. TaskOutput: Fetches the streamed output / progress log appended to a task (with optional tail to limit to the most recent entries).
5. TaskUpdate: Updates a task's fields — its description or status. Setting the status to deleted permanently removes the record.
6. TaskStop: Abandons an in_progress task — it resets the status back to pending and clears the task's owner (with an optional reason recorded in the output log). It does not complete the task; use TaskUpdate with status: completed for genuinely finished work. The task must currently be in_progress, or the call errors.

Working with Tasks

You do not need to run task tools manually; the agent uses them automatically. The read-only and record-keeping task tools (TaskCreate, TaskList, TaskGet, TaskOutput, TaskUpdate, TaskStop) run without an approval prompt — it's the underlying file edits and shell commands that the agent runs alongside them that surface approval cards in BUILD mode. The agent can periodically check a task's output (using TaskOutput) to verify, for example, that a dev server started without errors.