AgentUse: Open-source agent runtime

agentuse run

Execute an agent file.

Syntax

agentuse run <agent-file> [prompt...] [options]

Arguments

string

required

Path to agent file (.agentuse or .md extension) or HTTPS URL

string

Optional additional prompt to append to the agent’s instructions

Options

-q, --quiet             Suppress info messages (only show warnings/errors)
-d, --debug             Enable verbose debug logging
--no-tty                Disable TUI output (plain logs for piping/automation)
-v, --verbose           Show detailed execution information
--timeout <seconds>     Maximum execution time in seconds (default: 300)
-C, --directory <path>  Run as if agentuse was started in <path> instead of the current directory
--env-file <path>       Path to custom .env file
-m, --model <model>     Override the model specified in the agent file
--mock                  Mock all tool outputs with the LLM instead of executing them (no real side effects). Requires --mock-model.
--mock-model <model>    Model that generates mock tool outputs (required with --mock; pick a cheap, reachable model)
--mock-approval [d]     Resolve the await_human gate deterministically instead of suspending: approve (default), reject, or comment:<text>

The --quiet and --debug options cannot be used together.

You can also set NO_TTY=true to force plain logging without spinners.

Directory and Path Resolution

Directory Override (-C, —directory)

The -C or --directory option is the starting directory for the command:

# Without -C: runs from current directory
agentuse run agent.agentuse

# With -C: starts from the specified directory
agentuse run agent.agentuse -C /path/to/project-or-subdir

Project Root Detection

AgentUse searches from the current directory upward for .agentuse/, .git/, or package.json. If none are found, the starting directory is the project root. The project root is used for:

Loading .env files
Finding plugins in .agentuse/plugins/
Owning shared stores in .agentuse/store/
Grouping session state

For agentuse serve, -C also defines the served scope: only .agentuse files under that directory are exposed, while state still belongs to the detected project root. This is useful for:

Running agents from different projects
CI/CD environments with complex directory structures
Testing with different configurations

Path Resolution Rules

Subagent paths and MCP server commands are resolved relative to the agent file’s directory.

See Agent Syntax - Subagents for complete path resolution examples.

Model Override

The --model option allows you to override the model specified in an agent file at runtime. This is useful for:

Testing: Compare agent behavior across different models
Cost Optimization: Use cheaper models for development/testing
Environment-Specific Models: Different models for dev/staging/production
Quick Experiments: Try new models without editing files

Format

provider:model[:env]

Where:

provider: A built-in provider (anthropic, openai, openrouter, opencode-go, bedrock) or a custom provider name
model: The specific model name (e.g., claude-sonnet-4-6, gpt-5.5, glm-5-flash:q4_K_M), or a version alias such as claude-sonnet
env: Optional environment suffix for API keys (e.g., dev, prod, or full env var name), built-in providers only

A configured @name alias also works: --model @fast.

Examples

# Override with OpenAI GPT-5
agentuse run agent.agentuse --model openai:gpt-5.6
agentuse run agent.agentuse --model opencode-go:kimi-k2.7-code

# Use Anthropic Claude Haiku for quick testing
agentuse run agent.agentuse -m anthropic:claude-haiku-4-5

# Track the newest model in a line, or use a configured alias
agentuse run agent.agentuse -m anthropic:claude-sonnet
agentuse run agent.agentuse -m @fast

# Use different API key via environment suffix
agentuse run agent.agentuse --model openai:gpt-5.6:dev
agentuse run agent.agentuse --model opencode-go:kimi-k2.7-code:dev
# This will use OPENAI_API_KEY_DEV instead of OPENAI_API_KEY

# Use specific environment variable
agentuse run agent.agentuse --model anthropic:claude-sonnet-5:ANTHROPIC_API_KEY_PERSONAL

When overriding models, provider-specific options (like OpenAI’s reasoningEffort) will be ignored if you switch to a different provider.

An explicit model override propagates to every nested sub-agent. Without --model, each agent uses the model declared in its own file; a parent’s configured model is not inherited. Alias fallback candidates and cooldowns propagate as one resolved policy and remain stable across session resume.

agentuse test

Test an agent in mock mode: side effects fabricated, approval gates auto-resolved, stores isolated. This is the recommended way to validate a new or changed agent before letting it run for real.

agentuse test <file> [prompt...]

Options:
--scope <scope>         What to mock: "gated" (only tools.bash.gated commands; everything else real)
                        or "all" (every tool result). Default: adaptive, "gated" when the agent
                        declares tools.bash.gated patterns, else "all".
--approval <decision>   Gate decision: approve (default), reject, or comment:<text>
                        (comments the first gate, approves the re-gate)
--mock-model <model>    Model that fabricates mock results (or set AGENTUSE_MOCK_MODEL once)

Plus the common run options (--quiet, --debug, --no-tty, --compact, --timeout, -C, --env-file, -m/--model, --json).

agentuse test my-agent.agentuse                          # adaptive scope, auto-approve
agentuse test my-agent.agentuse --approval reject        # exercise the cleanup branch
agentuse test my-agent.agentuse --scope all              # fabricate everything

Gated scope is the closed-loop testing mode: only the bash commands matching the agent’s tools.bash.gated patterns (the irreversible subset the author already fenced off) are fabricated, and the gates guarding them auto-approve. Every other tool (reads, non-gated bash, MCP, skills) runs for real, so the agent grounds itself in real project state. The run completes end-to-end, unattended, with zero irreversible side effects, and the session log shows the full gate flow (the await_human call with its changes[], the deterministic approval, the fabricated command result) for review.

Stores are isolated under mock: reads are seeded by copying the real store, writes land in <projectRoot>/.agentuse/store-mock/<timestamp>-<pid>/ (kept for inspection), and the real store, including the reserved metrics store behind dashboards, is never touched.
Test runs stay out of the ops views: mock sessions are excluded from the serve home dashboard (latest results, failure triage), agent health/sparklines, and the sessions list by default, and they never fire push notifications. Flip the sessions view’s “mock runs” filter to shown/only mock (API: ?mock=include|only) to see them; a mock session’s detail page is always reachable by id.
In the effect WAL, a fabricated gated command has a lease-approved entry but no bash-spawn entry; that absence is the audit signal it never executed.
An agent with no tools.bash.gated patterns under gated scope gets a warning: nothing is mocked, everything runs real (with gates auto-resolved).

Only gated bash commands are fabricated under gated scope. Effectful MCP tools or channel posts still run for real; pair with a scratch copy of the project when the agent writes through those. And a fabricated command changes nothing on disk, so a later real command that checks its effect (e.g. git log after a fabricated git push) will see the unchanged state.

Full mock (`--scope all`, or `run --mock`)

Full-scope mock answers every tool call with an LLM-generated result instead of executing it. The agent runs for real; only tool execution is faked. The same mode is available as low-level plumbing on run:

agentuse run agent.agentuse --mock --mock-model anthropic:claude-haiku-4-5

Use the lowest-end model you can reach for --mock-model. Mocking is not a reasoning task: the model only has to fabricate a plausible result for a tool given its name and arguments. Your agent’s actual reasoning still runs on its own model, untouched. A small, fast model produces fine mock output while keeping cost and rate-limit pressure low, which matters because mock fires one LLM call for every tool result (and they run concurrently when the agent batches tool calls).Good low-end picks, by provider:

Provider	Suggested `--mock-model`
`anthropic`	`anthropic:claude-haiku-4-5`
`openai`	`openai:gpt-5.4-nano`
`openrouter`	`openrouter:deepseek/deepseek-v4-flash`

Pick one in a provider you’re authenticated for. (Model IDs drift over time; the current low-end tier is the rule, not these exact names.)

A mock model is required. Mock fires an LLM call for every tool result, so it must run on a model you can reach. It is deliberately not defaulted to the agent’s own model: that ran mock onto the agent’s premium, rate-limited token and produced opaque 429s. Provide it per run with --mock-model, or set a global default once via AGENTUSE_MOCK_MODEL in the shell, ~/.agentuse/.env, or the env block of ~/.agentuse/config.json. The flag wins over all of them.
Sub-agents run for real; their leaf tools are mocked.
The approval gate stays real under run --mock: await_human still suspends so you can verify the agent pauses for approval. Pass --mock-approval for fully-unattended runs (agentuse test defaults to this): the gate resolves deterministically (no LLM plays the reviewer) instead of suspending.
- --mock-approval (or --mock-approval approve) auto-approves. The approval grants the gated-command lease derived from the gate’s changes[] exactly like a real reviewer approval, so tools.bash.gated flows complete end-to-end. On a pick gate the recommended option is chosen (else the first), returned as choice.
- --mock-approval reject forces the reject branch: the gate seals (terminal for the run) so you can test the agent’s cleanup path.
- --mock-approval comment:<text> forces the revise-and-re-gate branch with <text> as the reviewer comment. The comment applies to the first gate only; the re-gate that follows is approved, so the run exercises the revision path and still finishes. (Repeating the comment on every gate would loop an obedient agent until it gave up.)

MCP servers still connect at startup for tool discovery, but no tool executes (no mutations). Mock outputs are non-deterministic; mocked approval decisions are deterministic.

Remote Agent Security

When running agents from remote URLs:

HTTPS Only: Only HTTPS URLs are allowed for security
File Extension: Remote agents must have .agentuse extension
Interactive Confirmation: AgentUse will show a security warning with options:
- [p]review - Fetch and display the agent content before running
- [y]es - Execute the agent directly
- [N]o - Abort execution (default)

Example security prompt:

⚠️  WARNING: You are about to execute an agent from:
https://example.com/agent.agentuse

Only continue if you trust the source and have audited the agent.

[p]review / [y]es / [N]o:

Examples

# Run agent from current directory
agentuse run hello.agentuse

# Run agent from subdirectory
cd agents/subfolder
agentuse run my-agent.agentuse  # Finds .env and plugins at project root

# Change to different directory first with -C
agentuse run agent.agentuse -C /my/project  # Same as: cd /my/project && agentuse run agent.agentuse

# Run agent from a different project
agentuse run newsletter/writer.agentuse -C ~/projects/content

# Use custom environment file
agentuse run agent.agentuse --env-file .env.production

# Run with additional prompt
agentuse run assistant.agentuse "Help me write an email"

# Run with multi-word prompt
agentuse run code-review.agentuse "focus on security and performance issues"

# Run remote agent (requires HTTPS and .agentuse extension)
# Shows security warning and requires confirmation
agentuse run https://example.com/agent.agentuse

# Run remote agent with additional prompt
agentuse run https://example.com/agent.agentuse "use production settings"

# Run with debug output
agentuse run agent.agentuse --debug

# Run with additional prompt and verbose output
agentuse run agent.agentuse "be thorough" --verbose

# Run with custom timeout
agentuse run agent.agentuse --timeout 600

# Run quietly (only warnings/errors)
agentuse run agent.agentuse --quiet

# Disable TUI output for piping/automation
agentuse run agent.agentuse --no-tty

# Override model at runtime
agentuse run agent.agentuse --model openai:gpt-5.4-mini

# Override model and add prompt
agentuse run agent.agentuse "be concise" --model anthropic:claude-haiku-4-5

# Use development API key with model override
agentuse run agent.agentuse -m openai:gpt-5.6:dev

# Override model for agent with sub-agents (all will use the same model)
agentuse run orchestrator.agentuse --model openai:gpt-5.4-mini

agentuse sessions

View and resume AgentUse sessions.

Syntax

agentuse sessions list [options]
agentuse sessions show <id> [options]
agentuse sessions resume <id> [options]
agentuse sessions reconcile [options]
agentuse sessions path [options]

agentuse sessions is a shortcut for agentuse sessions list. Session data is stored globally and partitioned by project. CLI session commands default to the current project; use --all or --all-search when you are not sure which project owns a session.

List Sessions

agentuse sessions list
agentuse sessions list --all
agentuse sessions list --project ../other-project

List options:

-s, --subagents          Include subagent sessions
-n, --limit <n>          Limit number of sessions to show
-j, --json               Output as JSON
--no-mock                Hide mock/test runs (listed by default, marked "· mock")
--all                    Show sessions across all projects
--project [path]         Show sessions for a project path; defaults to current project

Show a Session

agentuse sessions show 01K...
agentuse sessions show 01K... --all-search
agentuse sessions show 01K... --project ../other-project

Show options:

-j, --json               Output as JSON
-f, --full               Show full tool input/output
--project [path]         Search a project path; defaults to current project
--all-search             Search all projects if not found in the selected project

Resume a Session

Use agentuse sessions resume for local continuation. It supports suspended approval sessions and ended sessions. For a suspended approval session:

agentuse sessions resume 01K... --approve
agentuse sessions resume 01K... --approve "Looks good"
agentuse sessions resume 01K... --reject "Not ready"
agentuse sessions resume 01K... --comment "Please revise the CTA"
agentuse sessions resume 01K... --comment "Keep intros factual, not salesy" --remember
agentuse sessions resume 01K... --comment "Please revise with citations" --remember "Always include source links before publishing."

The CLI uses local session access as the trust boundary, so approval resumes do not require a resume token. --remember saves the comment as a future instruction, and requires --comment (a non-empty one). Bare --remember reuses the comment text; passing a value (--remember "...") overrides it. Passing --remember is itself the opt-in, so saving needs no learning config on the agent. The comment is still the feedback for this revision; the instruction is distilled from it, stored as src:manual, and injected into future runs once the agent has learning.apply enabled. It is also vetted against the agent’s own instructions: a note that contradicts them is still saved, but quarantined with the conflict named rather than injected. For a suspended non-approval await_* tool:

agentuse sessions resume 01K... --tool-result '{"status":"done"}'

For a completed or errored session, AgentUse starts a new run from the original agent file with continuation context:

agentuse sessions resume 01K... --prompt "Continue from here and add tests"

Resume options:

-C, --directory <path>   Run as if agentuse was started in <path>
--project [path]         Search a project path; defaults to current project
--all-search             Search all projects if not found in the selected project
-d, --debug              Enable debug logging for resume

Reconcile Stuck Sessions

Settle sessions still marked running whose owning process is gone. This is the same owner-liveness check agentuse serve performs at startup, but it sweeps as far back as you ask instead of the daemon’s 30-day window.

agentuse sessions reconcile [options]

Reconcile options:

--lookback <spec>        How far back to scan: a day count, or "all" (default: all)
--dry-run                Report what would be settled without writing
-j, --json               Output as JSON
--all                    Reconcile across all projects
--project [path]         Reconcile a project path; defaults to current project

A run that is still executing anywhere is never touched: a live worker, a worker released across a daemon restart, or a plain terminal agentuse run all keep their session as-is, because the session records its owning process and reconcile checks that the process is actually alive. A 10-minute recency window backs that up, so a session written to very recently is left alone even if it comes from a build that predates owner tracking. Sessions suspended on a subagent that died are settled the same way, so a manager waiting on a child that will never report back stops sitting in limbo.

Why this exists: runs orphaned before serve’s 30-day startup window stayed running forever, inflating the dashboard’s needs-attention counts with work that ended long ago.

# See what is stuck without changing anything
agentuse sessions reconcile --dry-run

# Settle everything in this project, however old
agentuse sessions reconcile

# Sweep the last week across every project, as JSON
agentuse sessions reconcile --all --lookback 7 --json

Show Storage Path

agentuse sessions path
agentuse sessions path --project ../other-project

agentuse serve

Start the AgentUse HTTP daemon to run agents via API. This enables integration with external applications, webhooks, approvals, Slack notifications, or any system that can make HTTP requests.

Syntax

agentuse serve [options]

Options

-p, --port <number>     Port to listen on (default: 12233)
-H, --host <string>     Host to bind to (default: 127.0.0.1)
-C, --directory <path>  Directory to serve agents from; project state is detected upward
--default <id>          Default project for POST /api/run when `project` is omitted
-d, --debug             Enable debug mode
--no-auth               Disable API key requirement for exposed hosts (dangerous)
--no-log-file           Disable writing serve logs to a file
--hide-agent-source     Hide raw agent source in the dashboard and /api/agents/detail

Serving Multiple Projects

AgentUse runs one serve daemon at a time. Repeat -C on that daemon to serve multiple scopes/projects:

agentuse serve -C ./projA -C ./projB

Project ids default to the -C directory basename. Duplicate ids fail startup. Each scope detects its project root independently, and each project loads its own .env / .env.local in its worker process. Use the request project field to choose a project. In multi-project mode, omitting it returns 400 PROJECT_REQUIRED unless --default <id> is set. Starting a second daemon fails with the PID, address, projects, and log path of the daemon that is already running. This keeps approval links, Slack replies, session resumes, and API traffic routed through one owner.

Global Config

You can put serve defaults in ~/.agentuse/config.json. See Configuration Files for the schema and CLI override behavior.

Authentication

When binding to exposed hosts (not 127.0.0.1 or localhost), API key authentication is required:

# Set API key for authentication
export AGENTUSE_API_KEY="your-secret-key"

# Start server on all interfaces
agentuse serve --host 0.0.0.0

Clients must include the key in requests:

curl -X POST http://server:12233/api/run \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "my-agent.agentuse"}'

Use --no-auth to bypass authentication (dangerous for production).

API Endpoints

All JSON endpoints are served under the /api/* prefix; the un-prefixed root paths (/, /agents, /sessions, /schedules, /stores, /approvals) serve HTML dashboard pages. GET / is the dashboard home: it links to those pages and lists the served projects with their agent and schedule counts. The per-session page /sessions/:id and its action subroutes (/decision, /continue, /status) carry their own capability auth (session token / API key / local). POST /run, POST /resume/:id, and the POST /approvals/:id/... action endpoints remain reachable at their original paths for backward compatibility, and GET /approvals/:id redirects to /sessions/:id (prefer the /api/* and /sessions paths; the legacy aliases will be removed later).

GET /api

Returns version, default project, and served projects. (GET / serves the HTML dashboard built from the same data.)

{
  "version": "0.12.0",
  "update": {
    "currentVersion": "0.12.0",
    "latestVersion": "0.18.0",
    "packageManager": "npm",
    "command": "npm install -g agentuse@latest"
  },
  "default": "projA",
  "projects": [
    { "id": "projA", "path": "/abs/path/to/projA", "agentCount": 3, "scheduleCount": 1 },
    { "id": "projB", "path": "/abs/path/to/projB", "agentCount": 2, "scheduleCount": 0 }
  ]
}

update is present only when the cached npm registry result contains a newer AgentUse version from npm’s latest dist-tag. The dashboard uses it for its dismissible update banner. default is null in multi-project mode without --default; single-project mode returns the sole project id.

POST /api/run

Execute an agent and receive the result. (Legacy alias: POST /run.) Request Body:

{
  "agent": "path/to/agent.agentuse",
  "project": "projA",
  "prompt": "Optional additional prompt",
  "model": "anthropic:claude-sonnet-5",
  "timeout": 300,
  "maxSteps": 100
}

Field	Type	Required	Description
`agent`	string	Yes	Path to agent file (relative to that project’s root)
`project`	string	Conditional	Required in multi-project mode unless `--default` is set
`prompt`	string	No	Additional prompt to append to agent instructions
`model`	string	No	Override the model specified in agent file
`timeout`	number	No	Maximum execution time in seconds (default: 300)
`maxSteps`	number	No	Maximum number of tool call steps

Response (JSON):

{
  "success": true,
  "result": {
    "text": "Agent response text",
    "finishReason": "end-turn",
    "duration": 1234,
    "tokens": { "input": 500, "output": 200 },
    "toolCalls": 3
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent file not found: my-agent.agentuse"
  }
}

GET /api/agents

Lists the agents loaded by the daemon as JSON. path is relative to the project root, exactly as accepted by POST /api/run. Agents that fail to parse are reported in errors rather than failing the request. The browsable HTML page is at /agents.

curl "http://127.0.0.1:12233/api/agents"

{
  "success": true,
  "agents": [
    {
      "projectId": "projA",
      "path": "daily.agentuse",
      "name": "Daily Digest",
      "description": "Posts a daily digest",
      "model": "anthropic:claude-sonnet-5",
      "schedule": "0 9 * * *"
    }
  ],
  "errors": []
}

description and schedule are present only when the agent declares them.

GET /api/agents/detail

Returns the capability summary and raw .agentuse source for one loaded agent. The endpoint is operator-gated like the rest of /api/*, and path must match an agent already loaded by the project.

curl "http://127.0.0.1:12233/api/agents/detail?project=projA&path=daily.agentuse" \
  -H "Authorization: Bearer $AGENTUSE_API_KEY"

The browsable agent detail hub is at /agents/<project>/<agent-path>.

GET /api/schedules

Lists the scheduled agents currently registered with the running daemon as JSON, sorted by next run (soonest first, disabled last). The browsable HTML page is at /schedules.

curl "http://127.0.0.1:12233/api/schedules"

{
  "success": true,
  "schedules": [
    {
      "id": "3252d076-d203-4921-b1c4-013d8748406b",
      "projectId": "projA",
      "agentPath": "daily.agentuse",
      "expression": "0 9 * * *",
      "human": "Daily 9am",
      "timezone": "America/Vancouver",
      "enabled": true,
      "jitterMs": 78721,
      "nextRun": "2026-06-03T16:00:00.000Z",
      "lastRun": null,
      "createdAt": "2026-06-02T21:00:42.371Z"
    }
  ]
}

nextRun and lastRun are ISO timestamps (or null). lastResult is included once a scheduled run has completed, and carries the run’s sessionId so the dashboard can deep-link to its log.

GET /api/sessions

Lists top-level runs as JSON, live first and then by most recent activity. Filters: ?agent=<id>, ?trigger=scheduled|manual|slack|api, and ?window=<1h|6h|24h|7d|30d|90d|all> (default 24h). Time windows use the last update, so a recently completed long-running session remains visible. The browsable HTML page is at /sessions.

curl "http://127.0.0.1:12233/api/sessions?agent=daily&trigger=scheduled" \
  -H "Authorization: Bearer $AGENTUSE_API_KEY"

{
  "success": true,
  "sessions": [
    {
      "project": "projA",
      "sessionId": "01JFN8K3M2P1",
      "agent": { "id": "daily", "name": "Daily Digest", "description": "Posts a daily digest" },
      "status": "completed",
      "trigger": "scheduled",
      "createdAt": 1717430400000,
      "updatedAt": 1717430412000
    }
  ],
  "window": { "value": "24h", "hours": 24, "updatedAfter": 1717344000000 },
  "errors": []
}

trigger is scheduled, api, slack, or manual (CLI runs and the default). For large histories, opt into cursor pagination with limit (maximum 100) and the opaque nextCursor returned by the prior response:

curl "http://127.0.0.1:12233/api/sessions?limit=50"

Supplying limit changes only the list length and adds limit and (when more records exist) nextCursor; requests without it retain the complete legacy response. Cursors are bound to the active filters and should be treated as opaque.

GET /api/sessions/:id

Returns one session including its run-log entries (logs). API-key gated. The human-facing view + approve page is /sessions/:id; see Approval Gates.

Error Code	HTTP Status	Description
`NOT_FOUND`	404	Endpoint not found (use `POST /api/run` or `GET /api`)
`AGENT_NOT_FOUND`	404	Agent file doesn’t exist
`PROJECT_NOT_FOUND`	404	Unknown project id in multi-project mode
`PROJECT_REQUIRED`	400	Multi-project request without `project` or `--default`
`INVALID_PATH`	400	Agent path outside project root
`INVALID_REQUEST`	400	Invalid JSON body
`MISSING_FIELD`	400	Required field missing
`TIMEOUT`	504	Agent execution timed out
`EXECUTION_ERROR`	500	Runtime error during execution
`INTERNAL_ERROR`	500	Unexpected server error

Streaming Response

For real-time output, request NDJSON streaming by setting the Accept header:

curl -N -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"agent": "my-agent.agentuse"}'

Each line is a JSON object representing an execution event:

{"type": "text", "text": "Analyzing..."}
{"type": "tool-call", "name": "read_file", "args": {"path": "data.txt"}}
{"type": "tool-result", "name": "read_file", "result": "..."}
{"type": "text", "text": "Complete!"}
{"type": "finish", "finishReason": "end-turn", "duration": 2345}

Examples

# Start server with defaults (127.0.0.1:12233)
agentuse serve

# Start on custom port
agentuse serve --port 8080

# Bind to all interfaces (for external access)
agentuse serve --host 0.0.0.0 --port 3000

# Set the public URL used in approval review links
agentuse serve --public-url https://agentuse.mycompany.com

# Provide Slack credentials for agents that enable Slack channels
SLACK_BOT_TOKEN=xoxb-... SLACK_APPROVAL_CHANNEL=C0123456789 agentuse serve

# Serve agents from a project or subdirectory
agentuse serve -C /path/to/project-or-subdir

# Host multiple projects from one process
agentuse serve -C ./projA -C ./projB

# Default POST /api/run to projA when `project` is omitted
agentuse serve -C ./projA -C ./projB --default projA

# Start with debug logging
agentuse serve --debug

API Usage Examples:

# Run an agent (JSON response)
curl -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "agents/assistant.agentuse"}'

# Run with additional prompt
curl -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "agents/writer.agentuse", "prompt": "Write about AI"}'

# Override model
curl -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "agents/helper.agentuse", "model": "openai:gpt-5.4-mini"}'

# Streaming response
curl -N -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"agent": "agents/analyzer.agentuse"}'

# Multi-project: pick which project runs the agent
curl -X POST http://127.0.0.1:12233/api/run \
  -H "Content-Type: application/json" \
  -d '{"project": "projA", "agent": "assistant.agentuse"}'

# Discovery: list served projects
curl http://127.0.0.1:12233/

Scheduled Agents

Agents with a schedule config in their frontmatter are automatically executed on schedule:

---
model: anthropic:claude-sonnet-5
schedule: "1h"
---

Scheduled Agents Guide

See the complete guide for intervals and cron expressions.

The server enables CORS by default. For production, run behind a reverse proxy with authentication.

serve ps

Show the running agentuse serve daemon.

agentuse serve ps [--json]

Shows PID, port, project summary, total agent/schedule counts, and uptime. Multi-project daemons show the first project id plus +N additional projects.

PID      PORT     PROJECTS                       AGENTS   SCHEDULES   UPTIME
────────────────────────────────────────────────────────────────────────────
63398    12233    projA +2                       12       3           2h 15m

Use --json for scripting. Stale entries are automatically cleaned up. While serve ps shows counts across daemons, use serve agents and serve schedules to inspect what a single running daemon actually loaded.

serve agents

List the agents loaded by the running daemon (queries its live GET /api/agents endpoint).

agentuse serve agents [pid] [--json]

AGENT           NAME          MODEL                        SCHEDULE
────────────────────────────────────────────────────────────────────
adhoc.agentuse  Adhoc Helper  anthropic:claude-haiku-4-5   —
daily.agentuse  Daily Digest  anthropic:claude-sonnet-5  0 9 * * *

Omit pid when only one daemon is running. Agents that failed to parse are listed after the table. Use --json for the raw payload. When the daemon requires an API key, set AGENTUSE_API_KEY so the command can authenticate.

serve schedules

List the scheduled agents in the running daemon (queries its live GET /api/schedules endpoint), sorted by next run.

agentuse serve schedules [pid] [--json]

NEXT RUN       AGENT           SCHEDULE   LAST RUN
──────────────────────────────────────────────────
Jun 03, 09:00  daily.agentuse  Daily 9am  never

agentuse schedules

Inspect and control deployment-local schedule state without changing agent frontmatter.

agentuse schedules
agentuse schedules pause <agent>
agentuse schedules resume <agent>

agentuse schedules lists declared schedules and whether each one is active or paused. pause and resume persist the override for the current deployment and notify a running daemon, when present. The declared cron expression or interval stays in the agent file and remains visible in the dashboard.

agentuse models

List the recommended models, the aliases they can be reached by, and your configured default.

agentuse models                  # recommended lineup + aliases
agentuse models anthropic        # one provider
agentuse models --all            # every model in the registry
agentuse models --verbose        # context limits, capabilities, alias per model

The Version aliases section shows what each version-less id (anthropic:claude-sonnet) resolves to right now. Your aliases and Default model appear when a models block is configured (see Configuration Files).

models unpin

Replace pinned model versions in agent files with version aliases, so those files track the newest release and stop needing edits:

agentuse models unpin --dry-run       # preview, current directory
agentuse models unpin ./agents        # apply to a directory
agentuse models unpin one.agentuse    # apply to a single file

agents/researcher.agentuse
  anthropic:claude-sonnet-5 → anthropic:claude-sonnet (currently anthropic:claude-sonnet-5)

models bump

Move superseded pins forward to the current model of the same product line, for files you want to keep pinned:

agentuse models bump --dry-run
agentuse models bump ./agents

Both commands only rewrite model references inside an agent file’s YAML frontmatter. Instructions below the frontmatter are left alone, since prose may legitimately name a specific model version. Version aliases are never rewritten by bump: they already track the line.

agentuse provider

Manage providers and authentication credentials. (auth still works as a hidden alias.)

agentuse provider login [provider]   # anthropic, openai, openrouter, opencode-go
agentuse provider login opencode-go

Amazon Bedrock authenticates via standard AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, optional AWS_SESSION_TOKEN) or AWS_BEARER_TOKEN_BEDROCK. There is no provider login bedrock command.

provider add

Add a custom OpenAI-compatible endpoint from the CLI (Ollama, LM Studio, vLLM, etc.). The dashboard can additionally configure OpenAI Responses and Anthropic Messages endpoints; see Model Configuration.

agentuse provider add ollama --url http://localhost:11434/v1
agentuse provider add lmstudio --url http://localhost:1234/v1
agentuse provider add myserver --url https://gpu.example.com/v1 --key sk-mykey

Then use: agentuse run agent.agentuse -m ollama:glm-5-flash:q4_K_M

Colons in model names are supported, ollama:qwen3.5:0.8b parses as provider ollama, model qwen3.5:0.8b.

provider remove / logout

agentuse provider remove ollama       # remove custom provider
agentuse provider logout openai       # remove built-in credentials

provider list

agentuse provider list
agentuse provider list --json   # machine-readable status; never includes secrets

agentuse skills

List and retrieve AgentUse builtin skills that ship with the installed CLI version. Use the installed subcommand to inspect project and user-installed skills.

Syntax

agentuse skills [subcommand] [options]

Subcommands

agentuse skills                 # List AgentUse builtin skills
agentuse skills list            # Explicit builtin list command
agentuse skills get <name>      # Output builtin skill content
agentuse skills get <name> --full
agentuse skills get --all       # Output every builtin skill
agentuse skills path [name]     # Print builtin skill paths
agentuse skills installed       # List installed/discovered skills
agentuse skills installed get <name>
agentuse skills installed path [name]

Options

-v, --verbose    Show skill file paths and tool requirements when listing
-j, --json       Output machine-readable JSON
--full           Include supporting files when using get
--all            Output every skill for the selected source when using get

Builtin Skills

Builtin skills are stored in the AgentUse package skill-data/ directory and match the installed CLI version. This mirrors the agent-browser skills model: agents can fetch current official instructions without reading a user’s entire local skill library.

Skill	Covers
`core`	The entry point: what AgentUse is, and which of the three below to fetch next
`runner`	Running agents, listing them, sessions, `serve`, schedules
`creator`	Authoring, improving, and reviewing `.agentuse` files
`tester`	Validating agents without real side effects: choosing a mock model and scope, exercising approval gates unattended, the edit-run-inspect loop, and the fidelity caveats of mock output

AI Coding Assistants

Install the assistant-facing AgentUse skill stub:

npx skills add agentuse/agentuse

For local development, install from this checkout:

npx skills add .

This installs the thin agentuse skill from skills/agentuse/SKILL.md. The stub points assistants at agentuse skills get core, so the real workflow guidance stays version-aligned with the installed AgentUse CLI.

Installed Skill Locations

Installed skills are discovered from these directories (in priority order):

.agentuse/skills/ - Project-specific skills
$AGENTUSE_CONFIG_DIR/skills/ - User-global skills (defaults to ~/.agentuse/skills/)
.claude/skills/ - Claude ecosystem compatibility
~/.claude/skills/ - Claude ecosystem compatibility
~/.agents/skills/ - Shared agent skills compatibility

Symlinked skill directories and SKILL.md files are supported. AgentUse skips dangling links, resolves directory real paths, and avoids circular traversal.

Examples

# List AgentUse builtin skills
agentuse skills
agentuse skills list

# Show verbose output with file paths and tool requirements
agentuse skills -v
agentuse skills --verbose

# Return machine-readable metadata
agentuse skills --json
agentuse skills list --json

# Print builtin skill content for an agent or script
agentuse skills get core
agentuse skills get runner
agentuse skills get creator
agentuse skills get tester
agentuse skills get core --full
agentuse skills get --all --json

# Print builtin paths
agentuse skills path
agentuse skills path core

# Inspect project and user-installed skills
agentuse skills installed
agentuse skills installed list --json
agentuse skills installed get code-review
agentuse skills installed get code-review --full
agentuse skills installed path code-review

Output Example

Found 3 builtin skill(s):

agentuse builtins
  core
    Core AgentUse usage guide...
  creator
    Create, improve, and review AgentUse agent files...
  runner
    Run and manage AgentUse agents from the CLI...

Installed skills:

Found 2 installed skill(s):

.agentuse/skills
  code-review
    Review code for quality, security, and maintainability...

With verbose mode (-v):

Found 2 installed skill(s):

.agentuse/skills
  code-review
    Review code for quality, security, and maintainability...
    /path/to/project/.agentuse/skills/code-review/SKILL.md
    tools: Read, Bash(git:*)

For detailed information on creating and using skills, see the Skills Guide.

agentuse doctor

Diagnose an agent’s skill capability configuration. Static mode inspects the agent file; --last-run inspects the most recent recorded session.

Syntax

agentuse doctor <file> [--last-run]

What It Checks

Static mode:

Recurring prompt cost per model request: the agent body, the full text of each preloaded skill, and the visible skill catalog, with a total.
Explicit skills that don’t exist on disk.
Explicit skills with no allow grants.
Commands mentioned in skill docs vs. what the agent has granted (advisory; not a permission manifest).
Learnings: how many of the stored ones are actually applied per run, and how many are over learning.max and so never reach the model, with agentuse learnings tidy <file> as the fix. It also reports how many are stale (the agent instructions changed since they were vetted, so they are held out of injection until the next capture or tidy re-vets them), a by channel: breakdown of what captured them (corrections, tool-errors, custom, agent, or legacy for entries predating channels), and every quarantined entry with the reason it failed the vet. It prints the resolved learnings file: path, echoes any one-time notice about a legacy learning: form, and warns when learnings are still sitting beside the agent file at the pre-0.17.0 location where nothing reads them.

--last-run mode:

Finds the latest non-subagent session for this agent.
Reports blocked bash commands from runtime and prints a suggested tools.bash.commands snippet.

Examples

# Static inspection
agentuse doctor agents/research.agentuse

# Diagnose actual blocked commands from the last run
agentuse doctor agents/research.agentuse --last-run

Prompt Size Warnings

Two costs recur on every model request, so doctor flags them:

What	Warns above	Warns harder above
Preloaded skills (the full text of everything in `skills:`)	~2,000 tokens	~4,000 tokens
Visible skill catalog (a name and description per discoverable skill)	~1,500 tokens	~3,000 tokens

The fix for either is the same shape: preload only what every run needs, and close discovery with skills.auto: false plus a shorter explicit list. Open discovery is the expensive default at scale, a machine with 100 skills installed pays roughly 11k tokens per request for the catalog alone.

Use --last-run after an agent fails or behaves unexpectedly. It uses real tool errors and is more accurate than static skill-doc extraction.

agentuse learnings

Inspect and tidy an agent’s stored learnings. Only the top few apply per run (15 by default, learning.max); anything past that is stored but never reaches the model, and so are entries that are quarantined (failed the vet) or stale (the agent instructions changed since they were vetted). See the Learning guide.

Syntax

agentuse learnings <agent-file> [--json] [--path] [--edit]
agentuse learnings tidy <agent-file> [--dry-run] [--model <model>]
agentuse learnings undo <agent-file>
agentuse learnings migrate [<agent-file>|--all] [--dry-run] [--keep-source|--delete-source]

Subcommands

Command	Description
(none)	List every learning by status: applied, never reaches the agent, stale (instructions changed, awaiting re-vet), quarantined (failed the vet, with the reason), in the agent file, retired.
`tidy`	Re-vet every learning the agent instructions have moved out from under, merge near-duplicates, sharpen learnings you have repeated, retire what is superseded, and make proven learnings permanent in the agent file. Applies immediately, then shows both diffs. Keeps making passes until another one would not help, up to five, and writes both files once at the end, so one run is one undo. Says what it is doing as it goes: a long list takes a few minutes. If it ends still over the cap, it accounts for every learning it left in force.
`undo`	Restore the learnings file and the agent file to their state before the last tidy-up, including anything that pass quarantined.
`migrate`	Move learnings written before v0.17.0 from beside the agent file into the AgentUse state directory. Copies first, then asks once before deleting the originals; refuses a destination that already holds learnings rather than merging; also lists any `*.learnings.md` with no matching agent file as orphaned.

Options

Option	Description
`-j, --json`	Machine-readable listing. Top level: `file` (the resolved learnings path), `cap`, and `active` / `injected` / `dormant` / `stale` / `quarantined` counts. Each entry in `learnings` carries its full record, including `channel`, `injectedCount`, `approvedRuns`, `instructionsHash`, and `quarantineReason`, plus a resolved `state` and computed `injected` and `stale` flags.
`--path`	Print the path of the learnings file and exit.
`--edit`	Open the learnings file in `$EDITOR` (or `$VISUAL`), creating its directory if needed.
`--dry-run`	(`tidy`) Show the plan and both diffs without writing anything. (`migrate`) Report what would move, including refusals, without writing anything.
`--model <model>`	(`tidy`) Plan with this model instead of the agent’s own.
`--all`	(`migrate`) Every agent file in the project, not one named agent.
`--keep-source`	(`migrate`) Keep the old files without asking.
`--delete-source`	(`migrate`) Delete the old files without asking. Required to delete anything when stdin is not a terminal, a non-interactive run never deletes on its own.

Examples

# What is actually reaching this agent?
agentuse learnings agents/blog-writer.agentuse

# Where does this agent's learnings file live?
agentuse learnings agents/blog-writer.agentuse --path

# See what a tidy-up would do, then do it
agentuse learnings tidy agents/blog-writer.agentuse --dry-run
agentuse learnings tidy agents/blog-writer.agentuse

# Changed your mind
agentuse learnings undo agents/blog-writer.agentuse

# Upgrading from before v0.17.0
agentuse learnings migrate --all --dry-run
agentuse learnings migrate --all
git commit -am "chore: move learnings to the agentuse state dir"

A tidy-up writes proven learnings into a marked block in your .agentuse file. Only the bytes inside the markers change, frontmatter, comments and formatting are left exactly as they were, and undo restores both files byte for byte.

Learnings no longer live beside your agent file. As of v0.17.0 they live under the AgentUse state directory, and the old location is never read. Run agentuse learnings migrate --all once per repo to copy them across; it will ask before removing the originals. migrate exits non-zero if it refused any file.

agentuse agents

Discover and list all agent files in the current project.

Syntax

agentuse agents [options]

Options

-v, --verbose    Show agent file paths

Examples

# List all agents in the project
agentuse agents

# Show verbose output with file paths
agentuse agents -v

Output Example

Found 3 agent(s):

agents/
  assistant
    General-purpose AI assistant
  code-reviewer
    Reviews code for quality and security
  researcher
    Researches topics and summarizes findings

agentuse add

Add skills and agents from GitHub repos or local paths.

Syntax

agentuse add <source> [options]

Arguments

string

required

Source to add. Supports:

GitHub shorthand: user/repo or user/repo#branch
Git URL: https://github.com/user/repo.git
Local path: ./path/to/repo
Direct skill: ./path/to/skill (directory containing SKILL.md)

Options

--force              Overwrite existing skills/agents without prompting
--all                Install all skills and agents without prompting
--list               List available skills and agents without installing
-s, --skill <name>   Install specific skill(s) by name (repeatable)
-a, --agent <path>   Install specific agent(s) by path (repeatable)

What Gets Added

Source Pattern	Destination
`**/SKILL.md` (parent dir)	`.agentuse/skills/{skill-name}/`
`*/.agentuse`	Same relative path in project

Examples

# Add from GitHub (interactive selection)
agentuse add vercel-labs/agent-skills
agentuse add vercel-labs/agent-skills#v1.0.0

# List available skills/agents without installing
agentuse add vercel-labs/agent-skills --list

# Install specific skills
agentuse add vercel-labs/agent-skills --skill react-best-practices
agentuse add vercel-labs/agent-skills -s skill-a -s skill-b

# Install specific agents
agentuse add user/repo --agent deploy.agentuse

# Install all without prompting
agentuse add user/repo --all

# Overwrite existing without prompting
agentuse add user/repo --force

# Add from local path
agentuse add ./my-skills-repo
agentuse add ./path/to/single-skill

Conflict Handling

When a skill or agent already exists, you’ll be prompted:

Skill "my-skill" already exists.
  [s] Skip  [o] Overwrite  [a] Skip all  [O] Overwrite all

agentuse help

Show help information.

Syntax

agentuse --help
agentuse -h
# Command-specific help
agentuse run --help
agentuse auth --help

Examples

# General help
agentuse --help

# Command-specific help
agentuse run --help
agentuse auth --help

# Show help when no arguments provided
agentuse

The agentuse config command is not yet implemented. Configuration is currently managed through environment variables only.

Global Options

--version              Show version number
--help, -h            Show help for command

Environment Variables

Control AgentUse behavior with environment variables. See Environment Variables Reference for complete documentation.

Exit Codes

AgentUse uses standard exit codes:

Code	Meaning
0	Success
1	General error
2	Authentication error
3	File not found
4	Model error
5	Tool error
6	MCP error
7	Network error
130	User interrupted (Ctrl+C)

Available Commands

AgentUse currently supports these commands:

agentuse run <file> [prompt...]          # Run an agent with optional prompt
agentuse test <file> [prompt...]         # Validate an agent in mock mode (no real side effects)
agentuse serve [options]                 # Start the HTTP daemon to run agents via API
agentuse serve ps [--json]               # Show the running serve daemon
agentuse serve schedules [pid] [--json]  # List schedules the running daemon is tracking
agentuse serve agents [pid] [--json]     # List agents the running daemon has loaded
agentuse sessions [list|show|resume|path] # View and resume sessions
agentuse sessions reconcile [--all]      # Settle runs stuck at "running"
agentuse provider login [provider]       # Authenticate with a provider
agentuse provider add <name> --url <url> # Add custom provider (Ollama, LM Studio, etc.)
agentuse provider logout [provider]      # Remove stored credentials
agentuse provider remove <name>          # Remove a custom provider
agentuse provider list                   # Show all providers and credentials
agentuse provider help                   # Show detailed auth help
agentuse models [provider] [options]     # List models, aliases, and the configured default
agentuse models unpin [path]             # Swap pinned model versions for version aliases
agentuse models bump [path]              # Move superseded pins to the current model
agentuse skills [subcommand] [options]   # List/get builtin or installed skills
agentuse doctor <file> [--last-run]      # Diagnose agent skill capability config
agentuse learnings <file> [--json]       # List an agent's stored learnings by status
agentuse learnings <file> --path         # Print where the learnings file lives
agentuse learnings tidy <file>           # Merge, sharpen, retire and make proven ones permanent
agentuse learnings undo <file>           # Restore both files to their pre-tidy state
agentuse learnings migrate --all         # Move pre-0.17.0 learnings into the state directory
agentuse agents [options]                # Discover and list project agents
agentuse add <source> [options]          # Add skills/agents from GitHub or local path
agentuse --version                       # Show version
agentuse --help                          # Show help

The agentuse auth command still works as a backward-compatible alias for agentuse provider.

Advanced Usage

Piping

# Pipe input to agent
echo "Translate this to Spanish" | agentuse run translator.agentuse

# Pipe agent output
agentuse run generator.agentuse | tee output.txt

# Chain agents
agentuse run analyzer.agentuse < data.txt | agentuse run summarizer.agentuse

Shell Integration

# Bash function
agent() {
  agentuse run "$1.agentuse" "${@:2}"
}

# Usage
agent translator "Hello world"

Batch Processing

# Process multiple files
for file in *.txt; do
  agentuse run processor.agentuse < "$file" > "processed_$file"
done

# Parallel processing
find . -name "*.md" | parallel agentuse run formatter.agentuse {}

Troubleshooting

Command not found

Ensure AgentUse is installed globally:

pnpm install -g agentuse

Permission denied

On Unix systems, you may need sudo:

sudo pnpm install -g agentuse

Authentication errors

If you see authentication errors, AgentUse will show specific guidance:

[ERROR] No API key found for anthropic

To authenticate, run:
  agentuse provider login

Or set your API key:
  export ANTHROPIC_API_KEY='your-key-here'

For more options: agentuse provider --help

Timeout issues

Increase timeout for long-running agents:

agentuse run agent.agentuse --timeout 600
# or via environment
MAX_STEPS=2000 agentuse run agent.agentuse

Debugging issues

Enable debug output:

agentuse run agent.agentuse --debug

​agentuse run

​Syntax

​Arguments

​Options

​Directory and Path Resolution

​Directory Override (-C, —directory)

​Project Root Detection

​Path Resolution Rules

​Model Override

​Format

​Examples

​agentuse test

​Full mock (--scope all, or run --mock)

​Remote Agent Security

​Examples

​agentuse sessions

​Syntax

​List Sessions

​Show a Session

​Resume a Session

​Reconcile Stuck Sessions

​Show Storage Path

​agentuse serve

​Syntax

​Options

​Serving Multiple Projects

​Global Config

​Authentication

​API Endpoints

​GET /api

​POST /api/run

​GET /api/agents

​GET /api/agents/detail

​GET /api/schedules

​GET /api/sessions

​GET /api/sessions/:id

​Streaming Response

​Examples

​Scheduled Agents

Scheduled Agents Guide

​serve ps

​serve agents

​serve schedules

​agentuse schedules

​agentuse models

​models unpin

​models bump

​agentuse provider

​provider login

​provider add

​provider remove / logout

​provider list

​agentuse skills

​Syntax

​Subcommands

​Options

​Builtin Skills

​AI Coding Assistants

​Installed Skill Locations

​Examples

​Output Example

​agentuse doctor

​Syntax

​What It Checks

​Examples

​Prompt Size Warnings

​agentuse learnings

​Syntax

​Subcommands

​Options

​Examples

​agentuse agents

​Syntax

​Options

​Examples

​Output Example

​agentuse add

​Syntax

​Arguments

​Options

agentuse run

Syntax

Arguments

Options

Directory and Path Resolution

Directory Override (-C, —directory)

Project Root Detection

Path Resolution Rules

Model Override

Format

Examples

agentuse test

Full mock (`--scope all`, or `run --mock`)

Remote Agent Security

Examples

agentuse sessions

Syntax

List Sessions

Show a Session

Resume a Session

Reconcile Stuck Sessions

Show Storage Path

agentuse serve

Syntax

Options

Serving Multiple Projects

Global Config

Authentication

API Endpoints

GET /api

POST /api/run

GET /api/agents

GET /api/agents/detail

GET /api/schedules

GET /api/sessions

GET /api/sessions/:id

Streaming Response

Examples

Scheduled Agents

serve ps

serve agents

serve schedules

agentuse schedules

agentuse models

models unpin

models bump

agentuse provider

provider login

provider add

provider remove / logout

provider list

agentuse skills

Syntax

Subcommands

Options

Builtin Skills

AI Coding Assistants

Installed Skill Locations

Examples

Output Example

agentuse doctor

Syntax

What It Checks

Examples

Prompt Size Warnings

agentuse learnings

Syntax

Subcommands

Options

Examples

agentuse agents

Syntax

Options

Examples

Output Example

agentuse add

Syntax

Arguments

Options

What Gets Added