Herdr Tutorial: Manage AI Coding Agents with Lumecoder API

What Herdr Solves

Herdr is a terminal multiplexer for coding agents. It organizes workspaces, tabs, and panes and recognizes idle, working, blocked, and done agent states.

Before You Start

Herdr commands must run inside a Herdr-managed pane.

test "${HERDR_ENV:-}" = 1
herdr --help
herdr workspace
herdr pane
herdr agent

Create a Pane and Start an Agent

Create a pane beside the current tab while keeping focus in the current pane. Read the new pane ID from the JSON response.

herdr pane split --current --direction right --cwd "$PWD" --no-focus
herdr agent start reviewer --kind codex --pane <pane-id>
herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

Connect the Agent to Lumecoder

Create an API token from the Use a key page in Lumecoder, then point your client's OpenAI-compatible endpoint and model configuration to Lumecoder. For a client that supports OpenAI Responses:

model = "gpt-5.6-sol"
model_provider = "lumecoder"

[model_providers.lumecoder]
name = "Lumecoder"
base_url = "https://lumecoder.com/v1"
env_key = "LUMECODER_API_KEY"

Set the token in the same pane where you start the agent:

export LUMECODER_API_KEY="你的 Lumecoder API Token"
curl https://lumecoder.com/v1/models \
  -H "Authorization: Bearer $LUMECODER_API_KEY"

Lumecoder is a third-party compatible service, not an OpenAI product. Check the console for available models, pricing, and access status. Keep API tokens out of Git repositories.

A Practical Multi-Agent Layout

workspace: lumecoder
├── tab: implementation
│   ├── pane: implementation agent
│   └── pane: tests or dev server
└── tab: review
    ├── pane: reviewer agent
    └── pane: logs

Let one agent implement and another review and test. This keeps every task observable while using the same Lumecoder API configuration.

Sources and Further Reading

• Herdr official websiteProduct overview, installation information, and releases.
• Herdr GitHub repositorySource code, command implementation, issues, and contribution guidance.

Troubleshooting

• Start failed: the target pane must be an interactive shell, not a foreground process.
• Authentication failed: check that the token is exported in the agent pane and that base_url includes /v1.
• Incomplete output: use recent-unwrapped; alternate-screen output may not be in host scrollback.