# How to Configure the FirstMate Backlog Backend with Tasks-Axi or Manual Mode

> Configure the FirstMate backlog backend for tasks-axi or manual mode. Learn how to set your work item rendering by editing the backlog-backend file.

- Repository: [Kun Chen/firstmate](https://github.com/kunchenguid/firstmate)
- Tags: how-to-guide
- Published: 2026-08-13

---

**TLDR:** Write either `tasks-axi` or `manual` to `$FM_HOME/config/backlog-backend` to control how FirstMate renders your work items; if the file is missing, the system defaults to the **tasks-axi** backend.

FirstMate processes your work items from [`data/backlog.md`](https://github.com/kunchenguid/firstmate/blob/main/data/backlog.md) during every session start. Choosing the correct backlog backend determines whether the tool leverages the external **tasks-axi** CLI for optimized rendering or falls back to a pure-shell **manual** implementation. This guide explains how to configure the FirstMate backlog backend using the source code from `kunchenguid/firstmate`.

## Understanding the Backlog Backend Configuration

The backend selection mechanism is straightforward but precise, relying on a single configuration file to dictate rendering behavior.

### The Configuration File Location

FirstMate checks for the backend preference at:

```sh
$FM_HOME/config/backlog-backend

```

If `$FM_HOME` is unset, the default location resolves to `$HOME/.firstmate`. The file contains exactly one line—either `tasks-axi` or `manual`—and is case-sensitive.

### Default Behavior and Fallback Logic

When the configuration file is absent, FirstMate automatically selects the **tasks-axi** backend. According to the source in [`bin/fm-session-start.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh), if `tasks-axi` is specified but the binary is missing or incompatible, the system gracefully falls back to **manual** mode and emits a diagnostic message.

## Configuring the Tasks-Axi Backend

The **tasks-axi** backend is the preferred method for rendering your backlog. It executes the external `tasks-axi` CLI to generate a compact view that omits **Done** rows, displays **In-flight**, **Held**, and **Blocked** items in full, and bounds the **Queued** section to a configurable limit.

To explicitly enable this backend:

```sh
mkdir -p "$FM_HOME/config"
echo tasks-axi > "$FM_HOME/config/backlog-backend"

```

The implementation resides in [`bin/fm-tasks-axi-lib.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-tasks-axi-lib.sh), which [`bin/fm-session-start.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh) invokes during session initialization. This library handles the binary execution, output parsing, and formatting logic.

### Customizing the Queued Row Limit

The tasks-axi backend respects the `FM_SESSION_START_QUEUED_LIMIT` environment variable. To display up to 10 queued items instead of the default 20:

```sh
export FM_SESSION_START_QUEUED_LIMIT=10

```

## Configuring the Manual Backend

Use the **manual** backend when the external `tasks-axi` CLI is unavailable or when you require a pure-shell implementation with no external dependencies. This mode parses [`data/backlog.md`](https://github.com/kunchenguid/firstmate/blob/main/data/backlog.md) directly and applies the same omission rules for completed items, though it handles queued row truncation differently (using a hard-coded bound of 4 rows).

To switch to manual mode:

```sh
mkdir -p "$FM_HOME/config"
echo manual > "$FM_HOME/config/backlog-backend"

```

As verified in [`tests/fm-session-start.test.sh`](https://github.com/kunchenguid/firstmate/blob/main/tests/fm-session-start.test.sh), setting the backend to `manual` forces the session start script to bypass the `tasks-axi` library and use the built-in parser instead. The [`tests/fm-teardown.test.sh`](https://github.com/kunchenguid/firstmate/blob/main/tests/fm-teardown.test.sh) suite confirms that manual mode still correctly triggers backlog updates during teardown.

## Verifying Your Backend Configuration

To confirm which backend is active, inspect the configuration file:

```sh
cat "$FM_HOME/config/backlog-backend" 2>/dev/null || echo "default (tasks-axi)"

```

For a dry-run view of the selection process:

```sh
fm-session-start.sh --dry-run | grep BACKLOG_BACKEND

```

## Summary

- Create `$FM_HOME/config/backlog-backend` containing either `tasks-axi` or `manual` to override defaults.
- The **tasks-axi** backend provides optimized rendering via the external CLI and is the default when no configuration file exists.
- The **manual** backend offers a dependency-free fallback implemented entirely in [`bin/fm-session-start.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh).
- Set `FM_SESSION_START_QUEUED_LIMIT` to control queued item display limits when using tasks-axi.
- Fallback logic automatically selects manual mode if the tasks-axi binary is missing, ensuring session continuity.

## Frequently Asked Questions

### What happens if I don't create the backlog-backend file?

If `$FM_HOME/config/backlog-backend` is absent, FirstMate defaults to the **tasks-axi** backend. If the external binary is also missing, the system automatically falls back to manual mode without requiring user intervention.

### Can I switch backends without restarting FirstMate?

Backend selection occurs during session initialization in [`bin/fm-session-start.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh). Changes to the configuration file take effect on the next session start, as the backlog is processed fresh each turn.

### Why does the manual backend show fewer queued items than tasks-axi?

The manual backend uses a hard-coded limit of 4 rows for queued items, while tasks-axi defaults to 20 rows (configurable via `FM_SESSION_START_QUEUED_LIMIT`). This difference is documented in the test suite at [`tests/fm-session-start.test.sh`](https://github.com/kunchenguid/firstmate/blob/main/tests/fm-session-start.test.sh).

### Where is the fallback logic implemented?

The fallback logic that detects missing or incompatible `tasks-axi` binaries and switches to manual mode is implemented in [`bin/fm-session-start.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh), which source-includes [`bin/fm-tasks-axi-lib.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-tasks-axi-lib.sh) for the primary backend operations.