Clarmanage

Clarmanage is the local runner for Armanage. It connects a machine you control to your Armanage workspace so assigned AI agents can pick up tasks, work inside your environment, and send progress back to the dashboard.

Tasks live in Armanage. Execution happens on your machine. The dashboard gets progress, not your codebase.

User Flow

1. Create an agent in Armanage and copy its token.
2. Install the runner:

npm install -g @armanage/clarmanage

3. If you use a self-hosted Armanage instance, point the runner to it:

export SERVER_BASE_URL="https://your-armanage.example.com"

For Claude-backed agents, also provide an Anthropic key before starting the runner:

export ANTHROPIC_API_KEY="your-anthropic-key"

For OpenCode-backed agents, provide credentials for the provider you want OpenCode to use and optionally pin the default model:

export OPENAI_API_KEY="your-openai-key"
export OPENCODE_MODEL="openai/gpt-5"

4. Connect the runner to your agent:

clarmanage agent add YOUR_AGENT_TOKEN

5. Start the runner:

clarmanage

If you need the full local debug log in the terminal, start it with:

clarmanage --full-debug

6. Create or assign tasks in Armanage. The runner picks them up, works locally, and keeps the dashboard updated with status and progress.
7. Review the result in Armanage and stop the runner with Ctrl+C when you're done.

If the runner is stopped while an agent is in the middle of a task, it now saves a local execution checkpoint under ~/.clarmanage/execution-checkpoints/. The next client start resumes that task before polling for new work. When the provider exposes a resumable session or thread, the runner restores that session; otherwise it continues from the preserved workspace state.

Daemon Mode

If the runner should stay alive in the background, start it as a daemon instead:

clarmanage daemon start

For verbose background logs:

clarmanage daemon start --full-debug

Manage the background process with:

clarmanage daemon status
clarmanage daemon stop
clarmanage daemon restart

By default, daemon state is stored in ~/.clarmanage/daemon.json and logs are written to ~/.clarmanage/daemon.log. If CLARMANAGE_CONFIG_DIR is set before startup, both files move under that directory.

clarmanage daemon stop and clarmanage daemon restart use the same checkpoint flow as foreground shutdown. Active tasks are paused first, their local progress is saved, and the next daemon start resumes them before any new task polling begins.

During long executions, the runner keeps sending busy heartbeats while work is active. If an execution produces no progress logs for EXECUTION_IDLE_TIMEOUT_MS milliseconds (default: 30 minutes), the runner aborts that stuck execution, marks it failed, and returns the agent loop to polling. Set EXECUTION_IDLE_TIMEOUT_MS=0 to disable the idle watchdog, or adjust WORK_HEARTBEAT_INTERVAL_MS to change the busy heartbeat cadence.

Useful Commands

clarmanage
clarmanage agent list
clarmanage agent remove
clarmanage daemon start
clarmanage daemon stop
clarmanage daemon restart
clarmanage daemon status

Repeat clarmanage agent add if you want the same machine to serve more than one agent profile.