dot-agent

Profile-based configuration manager for AI agents (Claude Code, etc.)

Overview

dot-agent manages reusable configuration profiles for AI coding assistants. Create profiles with skills, commands, rules, and instructions, then install them to any project.

Installation

# CLI only
cargo install dot-agent-cli

# With GUI
cargo install dot-agent-cli --features gui

Quick Start

# Create a new profile
dot-agent profile add my-profile

# List profiles
dot-agent profile list

# Install to a project
dot-agent install -p my-profile ~/my-project

# Check status
dot-agent status ~/my-project

# Upgrade to latest
dot-agent upgrade -p my-profile ~/my-project

# Show differences
dot-agent diff -p my-profile ~/my-project

# Remove from project
dot-agent remove -p my-profile ~/my-project

Profile Structure

~/.dot-agent/profiles/my-profile/
├── CLAUDE.md           # Main instructions
├── skills/             # Skill definitions
├── commands/           # Custom commands
├── rules/              # Project rules
└── agents/             # Agent configurations

Commands

Switching Profiles

switch replaces one installed profile with another while preserving your local modifications.

# Switch to a different profile (interactive conflict resolution)
dot-agent switch -p new-profile ~/my-project

# Switch and overwrite all conflicts without prompting
dot-agent switch -p new-profile ~/my-project --force

When local files differ from the profile, switch displays each conflict and prompts:

CONFLICT: rules/my-profile-testing.md
  [k] keep local   [o] overwrite with profile   [a] abort

• k — keep your local version (file is not overwritten)
• o — overwrite with the incoming profile version
• a — abort the entire switch operation

With --force, all conflicts are automatically overwritten without prompting. A snapshot is saved automatically before the switch so you can restore if needed.

Options

• --global / -g: Use ~/.claude as target
• --force / -f: Overwrite conflicts without prompting (used with install, upgrade, switch)
• --dry-run / -d: Preview without changes
• --no-prefix: Don't add profile prefix to filenames
• --gui: Launch GUI (requires gui feature)

Import from Git

# Import entire repository
dot-agent profile import https://github.com/user/my-profile

# Import subdirectory
dot-agent profile import https://github.com/user/repo --path profiles/rust

# Import specific branch
dot-agent profile import https://github.com/user/repo --branch develop

File Prefixing

By default, installed files are prefixed with the profile name to avoid conflicts:

• rules/testing.md → rules/my-profile-testing.md
• skills/tdd/SKILL.md → skills/my-profile-tdd/SKILL.md

Use --no-prefix to disable this behavior.

Snapshots

Snapshots allow you to save and restore states of both profiles (source) and installed targets.

Profile Snapshots

Save/restore profile source directories:

# Save current state
dot-agent profile snapshot save my-profile -m "before refactoring"

# List snapshots
dot-agent profile snapshot list my-profile

# Show changes since snapshot
dot-agent profile snapshot diff my-profile <id>

# Restore to previous state
dot-agent profile snapshot restore my-profile <id>

# Delete old snapshots, keep recent 5
dot-agent profile snapshot prune my-profile --keep 5

Target Snapshots

Save/restore installed configurations:

# Save current installation state
dot-agent snapshot save --path ~/my-project -m "working config"

# List snapshots
dot-agent snapshot list --path ~/my-project

# Show changes since snapshot
dot-agent snapshot diff <id> --path ~/my-project

# Restore to previous state
dot-agent snapshot restore <id> --path ~/my-project

# Prune old snapshots
dot-agent snapshot prune --keep 10 --path ~/my-project

Snapshots are automatically created before switch operations.

Crates

• dot-agent-cli: CLI binary and optional GUI
• dot-agent-core: Core library for profile management

License

MIT