AgentUse - Autonomous Agents That Work Without You

AgentUse reads configuration from agent files, environment files, global defaults, and project or user-level extension directories.

Quick reference

Path	Scope	Purpose
`*.agentuse`	Agent	Defines an agent with YAML frontmatter and Markdown instructions
`.env.local`	Project	Local environment variables loaded before `.env` when present
`.env`	Project	Environment variables for API keys, model providers, MCP servers, and runtime behavior
`--env-file <path>`	Run command	Load a specific environment file for `agentuse run`
`~/.agentuse/config.json`	User	Global `agentuse serve` defaults and an `env` block of variable defaults
`AGENTUSE_CONFIG=/path/to/config.json`	Process	Override the global config file path
`.agentuse/plugins/*.{ts,js}`	Project	Project-local plugins
`~/.agentuse/plugins/*.{ts,js}`	User	User-global plugins
`.agentuse/skills/`	Project	Project-local skills
`~/.agentuse/skills/`	User	User-global skills
`.claude/skills/`	Project	Claude ecosystem skill compatibility
`~/.claude/skills/`	User	Claude ecosystem skill compatibility
`{agent-name}.learnings.md`	Agent	Auto-created learning notes for agents with learning enabled
`{agent-name}.store.json`	Agent	Persistent store file for agents with store enabled

Agent files

Agent files use the .agentuse extension. They combine YAML frontmatter with Markdown instructions:

---
model: anthropic:claude-sonnet-5
description: Summarize pull requests
schedule: "0 9 * * 1"
tools:
  bash:
    commands:
      - "gh *"
---

Review open pull requests and summarize anything blocked.

Common frontmatter fields include model, tools, schedule, mcpServers, subagents, store, learning, sandbox, approval, channels, timeout, and maxSteps. See Agent Syntax for the full schema. Approval channels are configured separately from approval policy:

approval: true
channels:
  slack:
    events: [approval]
    channel_id: C0123456789

See Channels for event semantics and Approval Gates for the approval dashboard and API workflow.

Environment files

AgentUse loads environment variables from the project root. Project roots are detected by walking upward from the starting directory until .agentuse/, .git/, or package.json is found. If none are found, the starting directory is the project root. For agentuse run, .env.local takes priority when present, otherwise .env is used. You can also pass a specific file:

agentuse run agent.agentuse --env-file .env.production

For agentuse serve, -C selects the directory whose agents are served, while the detected project root owns .env.local, .env, .agentuse/store, and session state. Each served project loads its own .env.local or .env in that project’s worker process. Environment variables do not mix across served projects. Use environment files for provider API keys, MCP server credentials, and runtime controls such as MAX_STEPS, LOG_LEVEL, and AGENTUSE_TELEMETRY_DISABLED.

Never commit .env, .env.local, or other secret-bearing environment files.

See Environment Variables for supported variables and examples.

Global serve config

Put long-lived agentuse serve defaults in ~/.agentuse/config.json:

{
  "serve": {
    "projects": [
      { "path": "~/work/projA" },
      { "id": "b", "path": "~/work/projB" }
    ],
    "default": "projA",
    "port": 12233,
    "host": "127.0.0.1",
    "auth": true,
    "logFile": true
  }
}

Use AGENTUSE_CONFIG=/path/to/config.json to load a different file. Project paths may start with ~ or ~/. AgentUse runs one serve daemon at a time. Put every project that should accept /run, approval, and notification traffic into serve.projects, or pass repeated -C flags when starting the daemon.

Config key	Type	Description
`serve.projects`	array	Directories to serve agents from. Each item needs `path`; AgentUse detects the project root upward; `id` is optional
`serve.default`	string	Default project id when `POST /run` omits `project`
`serve.port`	number	Port to listen on
`serve.host`	string	Host to bind to
`serve.auth`	boolean	Require API key authentication for exposed hosts
`serve.logFile`	boolean	Write serve logs to a file

CLI flags override config values:

Config key	CLI override
`serve.projects`	`-C, --directory` replaces the configured project list
`serve.default`	`--default <id>`
`serve.port`	`--port <number>`
`serve.host`	`--host <string>`
`serve.auth`	`--no-auth` sets auth to `false`
`serve.logFile`	`--no-log-file` sets log files to `false`

AGENTUSE_API_KEY remains env-only and is not read from config. See Webhooks and CLI Commands for serve usage.

Global env defaults

Alongside serve, ~/.agentuse/config.json accepts an env block of environment variable defaults, mirroring the env key in Claude Code’s settings.json. Use it for non-secret defaults you want applied to every run without maintaining a separate ~/.agentuse/.env file:

{
  "env": {
    "AGENTUSE_MOCK_MODEL": "anthropic:claude-haiku-4-5"
  }
}

Values must be strings. The block is applied at startup and never overrides a variable that is already set, so the precedence is:

shell env  >  ~/.agentuse/.env  >  config.json "env"

Per-command flags still win over all of these. For example, --mock-model <model> overrides AGENTUSE_MOCK_MODEL from any source, and --mock is satisfied by a mock model coming from the flag, the shell, ~/.agentuse/.env, or the config env block. Keep secrets (like AGENTUSE_API_KEY and provider API keys) in an environment file rather than config.json, which is plain non-secret configuration.

Plugins

Plugins are TypeScript or JavaScript modules loaded from these directories:

.agentuse/plugins/*.{ts,js}
~/.agentuse/plugins/*.{ts,js}

Project plugins load before user-global plugins. See Plugins for the plugin API.

Skills

Skills are reusable instruction packs stored as SKILL.md files. AgentUse discovers skills in this order:

.agentuse/skills/
~/.agentuse/skills/
.claude/skills/
~/.claude/skills/

Use .agentuse/skills/ for project-specific skills and ~/.agentuse/skills/ for personal skills shared across projects. The .claude/skills/ locations provide compatibility with existing Claude skills. See Skills for authoring and discovery details.

Generated files and data locations

These files are generated by features rather than hand-written as primary configuration:

Path	Created by	Purpose
`{agent-name}.learnings.md`	Learning	Stores extracted guidance next to the agent file by default
`{agent-name}.store.json`	Store	Stores persistent key-value data for the agent
`.agentuse/sandbox/`	Sandbox	Stores sandbox-related working data
`.agentuse/benchmark/`	Benchmark	Stores local benchmark suites and results
`$XDG_DATA_HOME/agentuse/`	Session logging	Stores execution sessions, defaulting to `~/.local/share/agentuse/`

See Learning, Store, Sandbox, and Session Storage for details.

Getting Started

Building

Running

Reference

Configuration Files

Quick reference

Agent files

Environment files

Global serve config

Global env defaults

Plugins

Skills

Generated files and data locations

​Quick reference

​Agent files

​Environment files

​Global serve config

​Global env defaults

​Plugins

​Skills

​Generated files and data locations

Quick reference

Agent files

Environment files

Global serve config

Global env defaults

Plugins

Skills

Generated files and data locations