Kigi-CLI/crates/codegen/kigi-tui/docs/user-guide/20-background-tasks.md

# Background Tasks and Monitoring

Kigi runs long-lived processes without blocking the conversation. This document covers background commands, the `/loop` command, the `monitor` tool, and the scheduler.

---

## Background Commands

Set `background: true` on the `run_terminal_command` tool to run a command in the background. It returns a task ID immediately; retrieve output with `get_command_or_subagent_output`.

### How It Works

1. The agent calls `run_terminal_command` with `background: true`.
2. The command starts in the background.
3. The agent receives a `task_id` for later reference.
4. When the command completes, a notification appears in the conversation.

### Getting Output

Use the `get_command_or_subagent_output` tool to check on a background command or subagent:

- `get_command_or_subagent_output(task_id)` — current output and status without waiting
- `get_command_or_subagent_output(task_id, timeout_ms=30000)` — wait up to the given milliseconds for completion

### Waiting for Multiple Tasks

Use `wait_commands_or_subagents` to block on several tasks at once:

- `task_ids` — the list of task IDs to wait for (maximum 20)
- `mode` — `wait_any` returns when the first task completes; `wait_all` waits for every task
- `timeout_ms` — the maximum time to wait, in milliseconds (default: 30 seconds)

The tool returns the status and output for every task you list.

### Killing Background Tasks

Use `kill_command_or_subagent(task_id)` to terminate a running background task or subagent. The tool sends SIGTERM, then SIGKILL, to shell processes, and sends Cancel and Shutdown to subagents. It reports success if the task was killed or had already exited.

### Common Use Cases

- **Dev servers**: Start a development server and continue coding
- **Test suites**: Run tests in the background while working on fixes
- **Build processes**: Start a build and check results later
- **Long compilations**: Start a compile and continue with other tasks

---

## Send a Running Task to the Background

In the interactive TUI, press `Ctrl+G` to send the running foreground command to the background. Do this when:

- A command takes longer than expected.
- You want to ask the agent something else while a command runs.
- You realize a process is long-running after it has started.

The task keeps running, and you receive a notification when it completes.

---

## The /loop Command

`/loop` runs a prompt on a recurring interval. It is useful for polling tasks, periodic checks, and continuous monitoring.

### Syntax

```
/loop [interval] <prompt>
```

The interval format supports:

| Format | Example | Description        |
| ------ | ------- | ------------------ |
| `Ns`   | `60s`   | Every N seconds (minimum 60) |
| `Nm`   | `5m`    | Every N minutes    |
| `Nh`   | `2h`    | Every N hours      |
| `Nd`   | `1d`    | Every N days       |

### Examples

```
/loop 5m Check if the test suite passes and report any failures
/loop 2h Summarize new commits since the last check
/loop 60s Check if the dev server at localhost:3000 is responding
```

### Behavior

- The prompt fires immediately on creation, then repeats at the specified interval
- Each firing creates a new agent turn
- Recurring tasks auto-expire after 7 days
- Maximum 50 scheduled tasks can be active at once

---

## The monitor Tool

The `monitor` tool streams events from a long-running script. Each line of output becomes a notification in the conversation. The `monitor` tool is the streaming counterpart to `/loop`: use `/loop` for periodic checks, and use `monitor` for real-time event streams.

### How It Works

1. You provide a shell command (`command`) and a short `description` that appears in every notification.
2. Kigi merges the command's stdout and stderr into a single output file.
3. Each new line in that file becomes a notification delivered to the conversation.
4. The monitor runs until the command exits or you stop it.

### Script Guidelines

- **Always use `grep --line-buffered` in pipes.** Without it, pipe buffering delays events by minutes.
- **Handle transient failures in poll loops** (`curl ... || true`). One failed request should not stop the monitor.
- **Use selective filters.** Every line becomes a message, so never pipe raw logs.
- **Set poll intervals to match the source.** Use 30 seconds or more for remote APIs to respect rate limits, and 0.5 to 1 second for local checks.
- **Both stdout and stderr generate events.** Redirect output you don't want as events — for example, append `2>/dev/null` — or filter it out.

### Examples

```bash
# Watch for errors in a log file
tail -f /var/log/app.log | grep --line-buffered "ERROR"

# Monitor file changes in a directory
inotifywait -m --format '%e %f' /watched/dir

# Poll GitHub for new PR comments
last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
while true; do
  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  gh api "repos/owner/repo/issues/123/comments?since=$last" \
    --jq '.[] | "\(.user.login): \(.body)"'
  last=$now; sleep 30
done
```

### Persistent Monitors

Set `persistent: true` for monitors that should run for the lifetime of the session:

- PR monitoring
- Log tailing
- CI status watching

Stop persistent monitors with `kill_command_or_subagent(task_id)`.

### Volume Control

If a monitor produces too many events, Kigi stops it automatically. When this happens, restart the monitor with a tighter filter. Prefer `grep --line-buffered`, `awk`, or a wrapper script that emits only the events you care about.

---

## The Scheduler

The scheduler provides a lower-level API for creating recurring tasks. `/loop` is a convenience wrapper around the scheduler.

### scheduler_create

Create a scheduled task:

| Parameter        | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `interval`       | How often to run: `"5m"`, `"2h"`, `"1d"`, `"60s"`       |
| `prompt`         | The prompt text to execute on each fire                  |
| `fire_immediately`| Fire on creation in addition to the interval (default: `false`) |
| `recurring`      | Repeat (default: `true`) or fire once (`false`)          |
| `durable`        | Persist across sessions (default: `false`)               |

### scheduler_list

List all active scheduled tasks with their IDs, prompts, intervals, and next fire times.

### scheduler_delete

Cancel a scheduled task by ID. Returns success if the task was found and removed.

---

## The Tasks Pane

In the interactive TUI, press `Ctrl+B` to toggle the tasks pane. This pane lists, in a single view:

- Running subagents and their progress
- Active background tasks and their status
- Monitor and `/loop` tasks, each with a live line-count badge
- The task ID for each entry

To toggle the prompt queue instead, press `Ctrl+;`.

---

## Use Cases and Patterns

### Dev Server + Coding

Start a dev server in the background and continue coding:

```
Start the dev server with `npm run dev` in the background, then implement the login form.
```

The agent runs the dev server with `background: true` and continues writing code. When the server starts, you see a notification.

### Continuous Test Monitoring

```
/loop 5m Run the test suite and report any new failures since the last run
```

Every 5 minutes, the agent runs tests and reports only new failures.

### Log Monitoring

Use `monitor` to watch for specific events:

```
Monitor the application log for ERROR and WARN entries. Use:
tail -f /var/log/app.log | grep --line-buffered -E "ERROR|WARN"
```

Each error or warning appears as a notification in the conversation.

### CI Pipeline Watching

```
/loop 2m Check the status of the GitHub Actions run for this PR. Report when it completes.
```

---

## Best Practices

- **Use `background` for one-shot long commands** (builds, test suites, server starts)
- **Use `/loop` for periodic checks** (CI status, test runs, health checks)
- **Use `monitor` for real-time event streams** (log tailing, file watching)
- **Use `scheduler_create` with `recurring: false`** for delayed one-shot tasks
- **Keep monitor filters tight** — prefer `grep --line-buffered` over raw log streams
- **Do not use sleep loops** in normal commands to poll — use `get_command_or_subagent_output` with `timeout_ms` instead
- **Set reasonable poll intervals** — 30s+ for remote APIs to avoid rate limits, shorter for local checks