agentprofiles-cli 0.3.0 → 0.4.0

package/LICENSE.md

@@ -0,0 +1,5 @@
+# License
+
+Licensed under either of the [Apache License, Version 2.0](LICENSE-APACHE.md) or [MIT license](LICENSE-MIT.md) at your option.
+
+For more information about contributing to this project, see our top-level [CONTRIBUTING](https://github.com/hashintel/labs/blob/main/.github/CONTRIBUTING.md) policy.

package/README.md

@@ -1,47 +1,46 @@
 # agentprofiles-cli
 
-**Manage per-project configuration profiles for LLM agent tools via `direnv`.**
+**Manage named configuration profiles for LLM agent tools.**
 
-Currently supports [Claude Code](https://claude.ai/code) and [OpenCode](https://opencode.ai/).
+Supports 6 agents: [Claude Code](https://claude.ai/code), [Amp](https://amp.dev/), [OpenCode](https://opencode.ai/), [Codex](https://codex.dev/), [Gemini](https://gemini.google.com/), and [Augment](https://augment.dev/).
 
 ---
 
 ## The Problem
 
-You use an AI coding assistant. Maybe Claude Code, maybe OpenCode. You have multiple contexts where you work—personal projects, work repos, client codebases—and you want different settings, histories, or API keys for each.
+You use AI coding assistants. You have multiple contexts where you work—personal projects, work repos, client codebases—and you want different settings, histories, or API keys for each.
 
-**The tools support this.** Both Claude Code and OpenCode read their configuration from a directory specified by an environment variable (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`). Point the variable at a different directory, and you get a completely isolated profile.
+**The tools support this.** Each agent reads its configuration from a directory. Point that directory at a different location, and you get a completely isolated profile.
 
 **But managing this manually is tedious:**
 
-- You can't just set the variable in your shell config—that's global, one profile for everything.
-- You can't add it to each project's dotfiles—that's not portable across projects with similar needs.
-- You don't want to remember to export variables before launching your editor every time.
+- You can't just set a global symlink—that's one profile for everything.
+- You can't add symlinks to each project's dotfiles—that's not portable across projects with similar needs.
+- You don't want to remember to update symlinks before launching your editor every time.
 
-**agentprofiles-cli solves this.** It gives you named profiles, stores them centrally, and uses `direnv` to automatically activate the right profile when you enter a project directory.
+**agentprofiles-cli solves this.** It gives you named profiles, stores them centrally, and switches each agent's global config symlink to the profile you choose.
 
 ```sh
 # Create profiles once
 agentprofiles add claude work
 agentprofiles add claude personal
+agentprofiles add opencode work
 
-# Activate per-project
-cd ~/work/client-project
-agentprofiles set claude work --allow
-
-cd ~/personal/side-project
-agentprofiles set claude personal --allow
+# Activate when needed
+agentprofiles set claude work
+agentprofiles set opencode work
 
-# Now "cd" handles everything. Enter a directory, get the right profile.
+# Switch to a different context
+agentprofiles set claude personal
 ```
 
 ---
 
 ## FAQ
 
-### "Just use your global config"
+### "Just use your global symlink"
 
-**The problem:** There's only one global config. If you work across multiple contexts (personal/work/clients), you're constantly mixing histories, API keys, and settings that shouldn't mix.
+**The problem:** There's only one global symlink. If you work across multiple contexts (personal/work/clients), you're constantly mixing histories, API keys, and settings that shouldn't mix.
 
 Some people create separate user accounts on their machine for this. That works, but it's heavy-handed for what should be a simple configuration switch.
 
@@ -51,106 +50,75 @@ Some people create separate user accounts on their machine for this. That works,
 
 A profile should be defined once and _applied_ to projects, not duplicated into each one.
 
-### "Just set the env var before launching"
+### "Just update the symlink manually"
 
 **The problem:** This works for one-off commands, but breaks down for real workflows:
 
-- Interactive sessions that spawn subprocesses inherit the environment—but only if you remembered to set it.
-- Multiple terminals need the same treatment.
 - You have to remember which profile goes with which project, every time.
+- Multiple projects with the same profile need manual coordination.
+- Switching between projects means manually updating symlinks.
 
 Humans are bad at remembering things. Computers are good at it. Let the computer remember.
 
-### "Why direnv specifically?"
+### "Why symlinks instead of environment variables?"
 
-[direnv](https://direnv.net/) is a mature, widely-used tool for per-directory environment management. It:
+Symlinks are simpler and more direct:
 
-- Automatically loads/unloads environment variables when you `cd` in and out
-- Has a security model (`direnv allow`) so you explicitly trust changes
+- No shell hooks or environment variable management needed
 - Works with any shell (zsh, bash, fish, etc.)
-- Is already installed on many developer machines
-
-We didn't want to reinvent this. direnv does one job well; agentprofiles-cli just makes it easy to use for agent tool profiles.
+- Agents read config from their standard directory (e.g., `~/.claude`)
+- No need for external tools like direnv
+- Portable across machines (just update the symlink)
 
 ### "Do I really need another CLI tool?"
 
-Fair question. You could manage this yourself with handwritten `.envrc` files. agentprofiles-cli is worth it if you value:
+Fair question. You could manage this yourself with handwritten symlinks. agentprofiles-cli is worth it if you value:
 
 - **Named profiles** you can list, create, and remove
 - **Consistent file structure** without thinking about it
-- **Clean `.envrc` files** that only contain a small bootstrap block
-- **Guardrails** like profile name validation and direnv hook detection
+- **Fast profile switching** with one command
+- **Guardrails** like profile name validation and symlink verification
+- **Cross-agent support** for managing multiple tools at once
 
-If you're comfortable managing raw env vars yourself, you don't need this. But if you want the convenience of `agentprofiles set claude work`, this is for you.
+If you're comfortable managing raw symlinks yourself, you don't need this. But if you want the convenience of `agentprofiles set claude work`, this is for you.
 
 ---
 
 ## Requirements
 
-### Node.js 20+
+### Node.js 18+
 
 This is a Node.js CLI tool.
 
-### direnv (required)
-
-agentprofiles-cli generates direnv-compatible files. Without direnv installed and hooked into your shell, those files won't do anything.
-
-**Install direnv:**
-
-```sh
-# macOS
-brew install direnv
-
-# Ubuntu/Debian
-sudo apt install direnv
-
-# Or see https://direnv.net/docs/installation.html
-```
-
-**Hook it into your shell** (add to your shell's rc file):
-
-```sh
-# ~/.zshrc
-eval "$(direnv hook zsh)"
-
-# ~/.bashrc
-eval "$(direnv hook bash)"
-
-# ~/.config/fish/config.fish
-direnv hook fish | source
-```
+### No external dependencies
 
-After adding the hook, restart your shell or source the rc file.
+agentprofiles-cli uses symlinks, which are built into all modern operating systems. No direnv, no environment variable management, no shell hooks needed.
 
-**Verify it works:**
-
-```sh
-direnv --version
-```
-
-When you `cd` into a directory with an `.envrc`, you should see direnv print a message about loading or blocking the file.
+Just install the CLI and start creating profiles.
 
 ---
 
-## Installation
+## Quick Start
+
+### 1. Install
 
 ```sh
 npm install -g agentprofiles-cli
 ```
 
----
-
-## Getting Started
-
-### 1. Initialize
+### 2. Initialize
 
 ```sh
 agentprofiles setup
 ```
 
-This creates the config directory (`~/.config/agentprofiles/` by default) and sets up subdirectories for each supported agent tool.
+This creates the config directory (`~/.config/agentprofiles/` by default) and sets up:
 
-### 2. Create profiles
+- Subdirectories for each supported agent tool
+- A `_base` profile template for each agent
+- Shared directories for cross-agent resources
+
+### 3. Create profiles
 
 ```sh
 agentprofiles add claude work
@@ -165,32 +133,28 @@ agentprofiles add claude
 # Suggests a random name like "jolly-curie", or enter your own
 ```
 
-### 3. Activate a profile in a project
+### 4. Activate profiles
 
 ```sh
-cd /path/to/your/project
-agentprofiles set claude work --allow
+agentprofiles set claude work
+agentprofiles set opencode work
 ```
 
-This writes two files:
-
-- `.envrc` — with a small bootstrap block
-- `.envrc.agentprofiles` — with the actual export statements
+This creates symlinks:
 
-The `--allow` flag runs `direnv allow` automatically. Without it, you'll need to run `direnv allow` manually.
+- `~/.claude` → `~/.config/agentprofiles/claude/work`
+- `~/.config/opencode` → `~/.config/agentprofiles/opencode/work`
 
-### 4. Work normally
+The agents now read config from the active profiles.
 
-Now every time you `cd` into that project, direnv automatically exports `CLAUDE_CONFIG_DIR` pointing to your "work" profile. When you `cd` out, it unloads.
-
-### 5. Switch or remove profiles
+### 5. Switch profiles
 
 ```sh
 # Switch to a different profile
-agentprofiles set claude personal --allow
+agentprofiles set claude personal
 
-# Remove a profile from this project (keeps the profile itself)
-agentprofiles unset claude --allow
+# Switch back to base profile
+agentprofiles unset claude
 ```
 
 ---
@@ -204,42 +168,41 @@ agentprofiles unset claude --allow
 | `add <agent> [name]`    | Create a new profile                                |
 | `edit <agent> <name>`   | Open a profile's directory in your editor           |
 | `remove <agent> [name]` | Delete a profile (alias: `rm`)                      |
-| `set <agent> [name]`    | Activate a profile for the current directory        |
-| `unset <agent>`         | Deactivate a profile for the current directory      |
+| `set <agent> [name]`    | Activate a profile for an agent                     |
+| `unset <agent>`         | Switch an agent back to base profile                |
+| `status [agent]`        | Show current profile status                         |
+| `release <agent>`       | Stop managing an agent (restore original config)    |
 
 ### Common flags
 
-- `--allow` / `-y` — Auto-run `direnv allow` after modifying files (for `set` and `unset`)
 - `--quiet` / `-q` — Suppress the banner
 
----
+### Supported agents
 
-## How It Works
-
-### Files in your project
+- `claude` — Claude Code
+- `amp` — Amp
+- `opencode` — OpenCode
+- `codex` — Codex
+- `gemini` — Gemini
+- `augment` — Augment
 
-When you run `agentprofiles set claude work`, it creates/updates:
+> **Note on `agentprofiles edit` and `$EDITOR`**
+>
+> The `agentprofiles edit` command uses the `$EDITOR` environment variable if it is set. This value may include arguments, and common patterns like `EDITOR="code --wait"` are supported. When present, the editor command (plus its arguments) is invoked with the profile directory path appended.
 
-**`.envrc`** — Contains a small bootstrap block:
+---
 
-```sh
-### agentprofiles:begin
-watch_file .envrc.agentprofiles
-source_env_if_exists .envrc.agentprofiles
-### agentprofiles:end
-```
+## How It Works
 
-**`.envrc.agentprofiles`** — Contains the actual exports:
+### Symlink-based activation
 
-```sh
-# tool-generated; do not edit
+When you run `agentprofiles set claude work`, the tool creates a symlink:
 
-### agentprofiles:begin claude
-export CLAUDE_CONFIG_DIR="$HOME/.config/agentprofiles/claude/work"
-### agentprofiles:end claude
+```
+~/.claude → ~/.config/agentprofiles/claude/work
 ```
 
-Only the block between `### agentprofiles:begin` and `### agentprofiles:end` in `.envrc` is managed by this tool. Your other environment variables are left alone.
+The agent reads config from its standard directory (`~/.claude`). The symlink points to the active profile, so switching profiles is just updating the symlink target.
 
 ### Profile storage
 
@@ -250,74 +213,84 @@ Profiles are stored in your config directory:
 ├── config.json
 ├── claude/
 │   ├── .gitignore          # Ignores runtime artifacts
+│   ├── _base/              # Base profile (default)
+│   │   └── meta.json
 │   ├── work/
 │   │   └── meta.json       # Profile metadata
 │   └── personal/
 │       └── meta.json
-└── opencode/
-    ├── .gitignore
-    └── work/
-        └── meta.json
+├── opencode/
+│   ├── .gitignore
+│   ├── _base/
+│   │   └── meta.json
+│   └── work/
+│       └── meta.json
+└── _agents/                # Shared cross-agent resources
+    └── meta.json
 ```
 
-Each profile directory _is_ the config directory for that tool. When `CLAUDE_CONFIG_DIR` points to `~/.config/agentprofiles/claude/work`, Claude Code reads its settings, history, and cache from there.
+Each profile directory _is_ the config directory for that tool. When `~/.claude` points to `~/.config/agentprofiles/claude/work`, Claude Code reads its settings, history, and cache from there.
 
----
+### Shared directories
 
-## Troubleshooting
+The tool also manages shared resources:
 
-### "Nothing happens when I cd into the project"
+```
+~/.agents → ~/.config/agentprofiles/_agents/
+```
 
-direnv isn't hooked into your shell.
+This allows all agents to access shared skills, tools, and resources.
 
-1. Verify direnv is installed: `direnv --version`
-2. Add the hook to your shell rc file (see [Requirements](#direnv-required))
-3. Restart your shell or source the rc file
-4. Re-enter the directory or run `direnv reload`
+---
 
-### "direnv says the .envrc is blocked"
+## Troubleshooting
 
-This is direnv's security model. Run:
+### "The symlink isn't being created"
 
-```sh
-direnv allow
-```
+Debug checklist:
 
-Or use `--allow` when running `agentprofiles set` or `agentprofiles unset`.
+1. Check the profile exists: `agentprofiles list claude`
+2. Check symlink status: `ls -la ~/.claude`
+3. Verify permissions: Can you write to `~/.`?
+4. Run `agentprofiles status` to see the current state
 
-### "The env var isn't set correctly"
+### "The agent isn't reading the right config"
 
-Debug checklist:
+1. Verify the symlink points to the right place: `ls -la ~/.claude`
+2. Check the profile directory exists: `ls -la ~/.config/agentprofiles/claude/work`
+3. Verify the agent is reading from the symlinked directory (check agent settings)
 
-1. Check the files exist: `cat .envrc` and `cat .envrc.agentprofiles`
-2. Verify direnv loaded: `direnv status`
-3. Check the variable: `echo $CLAUDE_CONFIG_DIR`
-4. Look for conflicts: Are you exporting the same variable elsewhere?
+### "I want to use a different config location"
 
-Force direnv to reload:
+You can override the config directory:
 
 ```sh
-direnv reload
+export AGENTPROFILES_CONFIG_DIR=/path/to/config
+export AGENTPROFILES_CONTENT_DIR=/path/to/content
 ```
 
-### I already have a `.envrc`
+Or set `contentDir` in `config.json` to point to a different location.
 
-That's fine. agentprofiles only manages the section between its markers. Keep your existing content outside that block.
+### "I already have a symlink at ~/.claude"
 
-If you export the same variable elsewhere in the file, the last assignment wins.
+agentprofiles will overwrite it. If you have existing config there, move it first:
 
----
+```sh
+mv ~/.claude ~/.claude.backup
+agentprofiles set claude work
+```
 
-## What to Commit
+Then migrate your config from the backup to the new location.
 
-This depends on your team, but common approaches:
+### "How do I see what's currently active?"
 
-| File                   | Recommendation                                                                                                             |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `.envrc`               | **Commit it.** The bootstrap block is generic and portable.                                                                |
-| `.envrc.agentprofiles` | **Usually gitignore.** It contains paths that may differ per machine. Have each developer run `agentprofiles set` locally. |
+Use the `status` command:
 
-If your team uses identical paths (e.g., everyone uses defaults), committing `.envrc.agentprofiles` is fine.
+```sh
+agentprofiles status
+```
+
+This shows which profiles are active for each agent and the status of all symlinks.
 
 ---
 
@@ -325,7 +298,7 @@ If your team uses identical paths (e.g., everyone uses defaults), committing `.e
 
 ### Default locations
 
-- **Config directory:** `~/.config/agentprofiles/` (or `$XDG_CONFIG_HOME/agentprofiles/`)
+- **Config directory:** `~/.config/agentprofiles/`
 - **Content directory:** Same as config directory by default
 
 ### Environment variable overrides
@@ -339,24 +312,31 @@ You can also set `contentDir` in `config.json` to point to a different location.
 
 ---
 
-## Removing agentprofiles from a project
+## Removing agentprofiles from your machine
 
-To stop using agentprofiles in a specific project:
+To stop using agentprofiles for an agent:
 
 ```sh
-# Remove all agent blocks
-agentprofiles unset claude --allow
-agentprofiles unset opencode --allow
+# Switch back to base profile (keeps the symlink, but points to base)
+agentprofiles unset claude
+agentprofiles unset opencode
+```
 
-# Then manually remove the bootstrap block from .envrc
-# and delete .envrc.agentprofiles if it's now empty
+To completely remove agentprofiles (remove symlinks):
+
+```sh
+# Manually remove symlinks
+rm ~/.claude
+rm ~/.config/opencode
+rm ~/.agents
 ```
 
-Or manually:
+Or use the `release` command (if available in your version):
 
-1. Delete the `### agentprofiles:begin` / `### agentprofiles:end` block from `.envrc`
-2. Delete `.envrc.agentprofiles`
-3. Run `direnv allow`
+```sh
+agentprofiles release claude
+agentprofiles release opencode
+```
 
 ---
 
@@ -387,6 +367,12 @@ npm run format:check && npm run lint && npm run typecheck && npm run test
 
 ---
 
+## Contributors
+
+`agent-profiles-cli` was created by [Lu Nelson](https://github.com/lunelson). It is being developed in conjunction with [HASH](https://hash.dev/) as an open-source project.
+
+If you have questions, please create a [discussion](https://github.com/orgs/hashintel/discussions).
+
 ## License
 
-MIT
+`agent-profiles-cli` is available under either of the [Apache License, Version 2.0] or [MIT license] at your option. Please see the [LICENSE] file to review your options.