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

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 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:

$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, 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:

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

The implementation resides in bin/fm-tasks-axi-lib.sh, which 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:

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 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:

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

As verified in 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 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:

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

For a dry-run view of the selection process:

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.
• 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. 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.

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, which source-includes bin/fm-tasks-axi-lib.sh for the primary backend operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}