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

​
Quick reference

PathScopePurpose
*.agentuseAgentDefines an agent with YAML frontmatter and Markdown instructions
.env.localProjectLocal environment variables loaded before .env when present
.envProjectEnvironment variables for API keys, model providers, MCP servers, and runtime behavior
--env-file <path>Run commandLoad a specific environment file for agentuse run
~/.agentuse/config.jsonUserGlobal agentuse serve defaults
AGENTUSE_CONFIG=/path/to/config.jsonProcessOverride the global config file path
.agentuse/plugins/*.{ts,js}ProjectProject-local plugins
~/.agentuse/plugins/*.{ts,js}UserUser-global plugins
.agentuse/skills/ProjectProject-local skills
~/.agentuse/skills/UserUser-global skills
.claude/skills/ProjectClaude ecosystem skill compatibility
~/.claude/skills/UserClaude ecosystem skill compatibility
{agent-name}.learnings.mdAgentAuto-created learning notes for agents with learning enabled
{agent-name}.store.jsonAgentPersistent 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-4-6
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, timeout, and maxSteps. See Agent Syntax for the full schema.

​
Environment files

AgentUse loads environment variables from the project root. Project roots are detected from .agentuse/, .git/, or package.json. 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, 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 ~/.
Config keyTypeDescription
serve.projectsarrayProject roots to serve. Each item needs path; id is optional
serve.defaultstringDefault project id when POST /run omits project
serve.portnumberPort to listen on
serve.hoststringHost to bind to
serve.authbooleanRequire API key authentication for exposed hosts
serve.logFilebooleanWrite serve logs to a file
CLI flags override config values:
Config keyCLI 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.

​
Plugins

Plugins are TypeScript or JavaScript modules loaded from these directories:
  1. .agentuse/plugins/*.{ts,js}
  2. ~/.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:
  1. .agentuse/skills/
  2. ~/.agentuse/skills/
  3. .claude/skills/
  4. ~/.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:
PathCreated byPurpose
{agent-name}.learnings.mdLearningStores extracted guidance next to the agent file by default
{agent-name}.store.jsonStoreStores persistent key-value data for the agent
.agentuse/sandbox/SandboxStores sandbox-related working data
.agentuse/benchmark/BenchmarkStores local benchmark suites and results
$XDG_DATA_HOME/agentuse/Session loggingStores execution sessions, defaulting to ~/.local/share/agentuse/
See Learning, Store, Sandbox, and Session Storage for details.