Configuration Reference

Complete reference for AgentStash configuration files, directories, and provider definitions.

AgentStash stores its configuration and data in the ~/.config/agentstash/ directory.

Directory Structure

~/.config/agentstash/
├── state.json              # Application state and preferences
├── dotagents.yaml          # Dotagents (Hub) configuration
├── providers/              # Custom provider definitions
│   └── my-tool.yaml
├── backups/                # Automatic backups before sync
├── cas/                    # Content Addressable Storage
└── staging/                # Temporary staging area

Configuration Files

state.json

Stores application state including:

Sync directory path
Provider enable/disable states
Resource enable/disable states
UI preferences

dotagents.yaml

Configures the Dotagents (Hub) feature that distributes skills to all your AI tools via symlinks.

# Enable/disable Dotagents distribution
enabled: true

# Base path for the canonical source
base_path: "~/.agents"

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable Dotagents distribution
`base_path`	string	`~/.agents`	Directory containing your canonical skills

When enabled, AgentStash creates symlinks from each provider’s skills directory to ~/.agents/skills/, allowing all tools to share the same skill definitions.

Custom Providers

You can add support for additional AI tools by creating YAML files in ~/.config/agentstash/providers/.

Provider YAML Schema

# yaml-language-server: $schema=https://agentstash.dev/provider.schema.json

id: my-tool
name: "My Tool"

discovery:
  base_path: "~/.my-tool"
  exists_check: true

resources:
  - glob: "skills/**"
    handler: directory_bundle
    description: "My Tool skills"

hub_capabilities:
  - skills

Required Fields

Field	Type	Description
`id`	string	Unique identifier (lowercase, alphanumeric with hyphens)
`name`	string	Human-readable display name
`discovery.base_path`	string	Path where the tool stores its configuration
`resources`	array	List of resource configurations to sync

Discovery Configuration

Field	Type	Default	Description
`base_path`	string	required	Base path for the provider (supports `~`)
`exists_check`	boolean	`true`	Verify path exists before syncing

Resource Configuration

Each resource defines what files to sync:

Field	Type	Default	Description
`glob`	string	required	Glob pattern for matching files
`handler`	string	required	How to process matched files
`description`	string	`""`	Human-readable description
`default_enabled`	boolean	`true`	Whether enabled by default
`exclude`	array	`[]`	Glob patterns to exclude

Handler Types

Handler	Use Case
`file_copy`	Single files (e.g., `rules.md`, `config.json`)
`directory_bundle`	Directories as atomic units (e.g., `skills/**`)
`json_normalize`	JSON files (normalized before comparison)
`yaml_normalize`	YAML files (normalized before comparison)

Hub Capabilities

Enable Dotagents distribution for specific resource types:

hub_capabilities:
  - skills      # Distribute skills via symlinks
  - commands    # Distribute commands via symlinks

Available capabilities: skills, commands, hooks, agents, rules, prompts

Provider Configuration Paths

Each AI tool stores its configuration in a specific location. AgentStash reads from and syncs to these paths:

Provider	Configuration Path
Claude Code	`~/.claude`
Cursor	`~/.cursor`
Windsurf	`~/.codeium/windsurf`
OpenCode	`~/.config/opencode`
Cline	`~/.cline`
Continue	`~/.continue`
Roo Code	`~/.roo`
Goose	`~/.config/goose`
Codex	`~/.codex`
Gemini CLI	`~/.gemini`
GitHub Copilot	`~/.copilot`
Amp	`~/.config/agents`
Trae	`~/.trae`
Trae CN	`~/.trae-cn`

Environment Variables

AgentStash respects the following environment variables:

Variable	Description
`HOME`	User home directory (used for `~` expansion)
`XDG_CONFIG_HOME`	Alternative config directory (defaults to `~/.config`)

Backup Behavior

Before each sync operation, AgentStash automatically backs up affected files to ~/.config/agentstash/backups/. Backups are timestamped and can be restored if needed.