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
`ABOUT.md`	Directory	Optional dashboard identity and description for the project or folder containing it
`.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,
    "hideAgentSource": false,
    "brand": { "name": "Acme Operations" },
    "terms": {
      "project": "workspace",
      "folder": "team|teams"
    }
  }
}

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
`serve.hideAgentSource`	boolean	Hide raw `.agentuse` source in the dashboard and `/api/agents/detail`; capability summaries (model, tools, schedule) stay visible. For deployments where visitors may run and observe agents but should not read their instructions (demos, client sandboxes)
`serve.brand.name`	string	Your company name, shown beside the AgentUse wordmark, in page titles, and as the installed app name (max 60 chars)
`serve.terms.project`	string	Dashboard display noun for a project. Routes, API fields, and CLI output keep the technical name
`serve.terms.folder`	string	Dashboard display noun for a folder. Add an explicit plural as `singular	plural` for irregular nouns

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`
`serve.hideAgentSource`	`--hide-agent-source` sets it to `true` (the flag can only hide, never re-expose a config that hides)

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

Directory identity with `ABOUT.md`

Place an optional ABOUT.md in a served project root or a directory containing agents. The dashboard uses the file to label and describe that directory. It does not alter agent prompts, API routes, or scheduling. Plain Markdown becomes the longer body shown on the directory detail surface:

Automations owned by the Revenue Operations team.

Optional YAML frontmatter supplies compact display fields:

---
name: Revenue Operations
description: Pipeline and renewal automations
owner: Operations Platform
---

These agents reconcile CRM events and prepare renewal follow-ups.

Recognized frontmatter keys are name, description, and owner; scalar string or numeric values are normalized for display. Unknown keys and other value types are ignored. The body remains the longer description. AgentUse rejects symlinked and oversized ABOUT.md files so directory identity cannot disclose an unrelated local file or inflate API responses. serve.brand.name labels the whole deployment; ABOUT.md labels one served directory within it. Use serve.terms when the deployment calls projects or folders by different nouns.

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

Directory identity with `ABOUT.md`

Global env defaults

Plugins

Skills

Generated files and data locations

​Quick reference

​Agent files

​Environment files

​Global serve config

​Directory identity with ABOUT.md

​Global env defaults

​Plugins

​Skills

​Generated files and data locations

Quick reference

Agent files

Environment files

Global serve config

Directory identity with `ABOUT.md`

Global env defaults

Plugins

Skills

Generated files and data locations