> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethandshake.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the background writer

> Configure an agent CLI to update stale project briefs and repository maps.

The background writer updates project knowledge when the active agent does not
publish current documents. This feature can use model quota from the selected
agent account.

## Prerequisites

* Install at least one supported agent CLI.
* Authenticate the selected agent CLI.
* Complete `handshake setup`.

Supported writers are `claude`, `codex`, `opencode`, and `hermes`.

## Configure the writer

<Steps>
  <Step title="Start the configuration">
    Run:

    ```bash theme={null}
    handshake knowledge author setup
    ```
  </Step>

  <Step title="Enable automatic writing">
    Confirm that Handshake can use a background writer.
  </Step>

  <Step title="Select a writer">
    Select one of the detected agent CLIs.
  </Step>

  <Step title="Confirm the selection">
    Confirm the final configuration.
  </Step>
</Steps>

Handshake stores the configuration in `~/.handshake/authoring.json`.

## Check the configuration

Run:

```bash theme={null}
handshake knowledge author show
```

The output shows the enabled state, the selected writer, and queued authoring
jobs.

## Change the writer

Run one of these commands:

```bash theme={null}
handshake knowledge author set claude
handshake knowledge author set codex
handshake knowledge author set opencode
handshake knowledge author set hermes
```

## Test the writer

Run:

```bash theme={null}
handshake knowledge author test
```

You can also test a specified writer:

```bash theme={null}
handshake knowledge author test codex
```

This test checks that the CLI is installed and accepts a non-interactive
command. It does not publish project knowledge.

## Disable the writer

Run:

```bash theme={null}
handshake knowledge author off
```

Handshake continues to write factual checkpoints. It does not start background
model runs.