fix(github-app): use per-agent config directory via AGENT_NAME

.claude-plugin/marketplace.json

@@ -356,7 +356,7 @@
     {
       "name": "github-app",
       "description": "Automatic GitHub App token lifecycle for Claude Code sessions. Generates installation tokens on session start, monitors expiry via PreToolUse hook, and refreshes transparently before commands that need authentication.",
-      "version": "0.1.14",
+      "version": "0.2.0",
       "author": {
         "name": "Nathan Heaps"
       },

plugins/github-app/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "github-app",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "description": "Automatic GitHub App token lifecycle for Claude Code sessions. Generates installation tokens on session start, monitors expiry via PreToolUse hook, and refreshes transparently before commands that need authentication.",
   "author": {
     "name": "Nathan Heaps",

plugins/github-app/README.md

@@ -48,7 +48,7 @@ github-app:
 github-app:
   ref: "env-file://./.env.github-app" # relative to project
   # or
-  ref: "env-file://~/.config/agent/github-app.env" # absolute
+  ref: "env-file://~/.agents/<agent-name>/.config/github-app.env" # absolute
 ```
 
 The source should provide fields named:
@@ -81,7 +81,7 @@ Set before the session starts:
 
 ```bash
 export GITHUB_APP_ID="12345"
-export GITHUB_APP_PRIVATE_KEY_PATH="~/.config/agent/github-app.pem"
+export GITHUB_APP_PRIVATE_KEY_PATH="~/.agents/<agent-name>/.config/github-app.pem"
 export GITHUB_INSTALLATION_ID="67890"
 ```
 
@@ -90,7 +90,7 @@ export GITHUB_INSTALLATION_ID="67890"
 ```yaml
 github-app:
   github_app_id: "12345"
-  private_key_path: "~/.config/agent/github-app.pem"
+  private_key_path: "~/.agents/<agent-name>/.config/github-app.pem"
   github_installation_id: "67890"
 ```
 
@@ -104,15 +104,15 @@ The private key can be provided as:
 When using a PEM file directly, ensure correct permissions:
 
 ```bash
-chmod 600 ~/.config/agent/github-app.pem
+chmod 600 ~/.agents/<agent-name>/.config/github-app.pem
 ```
 
 ## How It Works
 
 1. **Session starts**: Hook reads App credentials, generates JWT, exchanges for installation token
-2. **Token stored**: Written to `~/.config/agent/github-token` with 600 permissions
+2. **Token stored**: Written to `~/.agents/${AGENT_NAME}/.config/github-token` with 600 permissions (where `AGENT_NAME` defaults to `_UNKNOWN` if unset)
 3. **Git identity configured**: Sets `git config user.name` and `user.email` to the App's bot identity (e.g., `my-app[bot]` / `12345+my-app[bot]@users.noreply.github.com`)
-4. **Runtime env file**: `GH_TOKEN` and `GITHUB_TOKEN` written to `~/.config/agent/github-app-env`, sourced by `CLAUDE_ENV_FILE`
+4. **Runtime env file**: `GH_TOKEN` and `GITHUB_TOKEN` written to `~/.agents/${AGENT_NAME}/.config/github-app-env`, sourced by `CLAUDE_ENV_FILE`
 5. **PreToolUse monitoring**: Before each tool call, checks token expiry (debounced to every 30s)
 6. **Smart refresh**: Commands using `gh`/`git push` get synchronous checks; others get async background refresh
 7. **Retry with backoff**: Failed refreshes retry up to 3 times, then back off for 5 minutes
@@ -152,7 +152,7 @@ github-app:
     github_installation_id: "${GITHUB_INSTALLATION_ID}"
 
   # Other settings
-  tokenFile: "~/.config/agent/github-token"
+  tokenFile: "~/.agents/<agent-name>/.config/github-token"
   autoGitConfig: true
 ```
 
@@ -191,6 +191,29 @@ plugins/github-app/
 └── README.md
 ```
 
+## Upgrading from 0.1.x
+
+### Migration
+
+v0.2.0 moves credential storage from `~/.config/agent/` to `~/.agents/${AGENT_NAME}/.config/`. On first session start after upgrading, a fresh token is generated under the new path. The old files at `~/.config/agent/` become orphaned and can be safely deleted:
+
+```bash
+rm -rf ~/.config/agent/github-token ~/.config/agent/github-token.meta ~/.config/agent/github-app-env
+```
+
+### AGENT_NAME for git credential helper
+
+`bin/git-credential-github-app.sh` is invoked by **git itself** outside the Claude harness. Git inherits the user's shell environment, where `AGENT_NAME` may not be set. To ensure the credential helper finds the correct per-agent token, export `AGENT_NAME` in your shell profile:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+export AGENT_NAME="jack"  # or "henry", etc.
+```
+
+Or in a systemd unit: `Environment=AGENT_NAME=jack`
+
+If `AGENT_NAME` is not set, the credential helper falls back to `~/.agents/_UNKNOWN/.config/`, which may collide with other unconfigured agents.
+
 ## Related
 
 - **[github](../github)** plugin — GitHub CLI installation, usage skill, and general auth

plugins/github-app/bin/git-credential-github-app.sh

@@ -7,11 +7,16 @@
 #   git config --global credential.https://github.blesdmm.dns-dynamic.net.helper \
 #     '!/path/to/git-credential-github-app.sh'
 #
-# The token file location defaults to ~/.config/agent/github-token
+# The token file location defaults to ~/.agents/${AGENT_NAME}/.config/github-token
 # but can be overridden via GITHUB_TOKEN_FILE environment variable.
 set -euo pipefail
 
-TOKEN_FILE="${GITHUB_TOKEN_FILE:-$HOME/.config/agent/github-token}"
+# shellcheck source=../lib/agent-paths.sh
+_self="${BASH_SOURCE[0]}"
+while [ -L "$_self" ]; do _self="$(readlink -f "$_self")"; done
+source "$(cd "$(dirname "$_self")/.." && pwd)/lib/agent-paths.sh"
+
+TOKEN_FILE="${GITHUB_TOKEN_FILE:-${AGENT_CONFIG_DIR}/github-token}"
 
 # Only respond to "get" requests
 case "${1:-}" in

plugins/github-app/bin/token-check.sh

@@ -32,9 +32,14 @@ done
 
 # --- Configuration ---
 
-TOKEN_FILE="${GITHUB_TOKEN_FILE:-$HOME/.config/agent/github-token}"
+# shellcheck source=../lib/agent-paths.sh
+_self="${BASH_SOURCE[0]}"
+while [ -L "$_self" ]; do _self="$(readlink -f "$_self")"; done
+source "$(cd "$(dirname "$_self")/.." && pwd)/lib/agent-paths.sh"
+
+TOKEN_FILE="${GITHUB_TOKEN_FILE:-${AGENT_CONFIG_DIR}/github-token}"
 META_FILE="${TOKEN_FILE}.meta"
-ENV_RUNTIME_FILE="${GITHUB_APP_ENV_FILE:-$HOME/.config/agent/github-app-env}"
+ENV_RUNTIME_FILE="${GITHUB_APP_ENV_FILE:-${AGENT_CONFIG_DIR}/github-app-env}"
 LOCKFILE="${TOKEN_FILE}.lock"
 COOLDOWN_FILE="${TOKEN_FILE}.cooldown"
 REFRESH_THRESHOLD_MINUTES=30
@@ -89,7 +94,7 @@ release_lock() {
 }
 
 # Get token minutes remaining (shared utility)
-PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+PLUGIN_DIR="$(cd "$(dirname "$_self")/.." && pwd)"
 source "$PLUGIN_DIR/lib/token-utils.sh"
 
 # Update the runtime env file with current token
@@ -114,7 +119,7 @@ ENVEOF
 # Generate a new token (full re-auth from keys)
 do_generate_token() {
   local script_dir
-  script_dir="$(cd "$(dirname "$0")" && pwd)"
+  script_dir="$(cd "$(dirname "$_self")" && pwd)"
 
   if [[ -z "${GITHUB_APP_ID:-}" || -z "${GITHUB_APP_PRIVATE_KEY_PATH:-}" || -z "${GITHUB_INSTALLATION_ID:-}" ]]; then
     log_error "missing credentials (APP_ID, PRIVATE_KEY_PATH, or INSTALLATION_ID)"

plugins/github-app/bin/token-status.sh

@@ -10,7 +10,12 @@
 # Output: JSON object with token status
 set -euo pipefail
 
-TOKEN_FILE="${GITHUB_TOKEN_FILE:-$HOME/.config/agent/github-token}"
+# shellcheck source=../lib/agent-paths.sh
+_self="${BASH_SOURCE[0]}"
+while [ -L "$_self" ]; do _self="$(readlink -f "$_self")"; done
+source "$(cd "$(dirname "$_self")/.." && pwd)/lib/agent-paths.sh"
+
+TOKEN_FILE="${GITHUB_TOKEN_FILE:-${AGENT_CONFIG_DIR}/github-token}"
 META_FILE="${TOKEN_FILE}.meta"
 
 # Check if token exists

plugins/github-app/docs/token-refresh-spec.md

@@ -70,9 +70,9 @@ The plugin uses two hooks and a set of CLI scripts:
 │  ┌────────────────────────────────────────────────┐   │
 │  │ Shared Files                                    │   │
 │  │                                                 │   │
-│  │ ~/.config/agent/github-token      (token)       │   │
-│  │ ~/.config/agent/github-token.meta (expiry/meta) │   │
-│  │ ~/.config/agent/github-app-env    (runtime env) │   │
+│  │ ~/.agents/${AGENT_NAME}/.config/github-token      (token)       │   │
+│  │ ~/.agents/${AGENT_NAME}/.config/github-token.meta (expiry/meta) │   │
+│  │ ~/.agents/${AGENT_NAME}/.config/github-app-env    (runtime env) │   │
 │  │                                                 │   │
 │  │ Read by: gh CLI ($GH_TOKEN), git credential     │   │
 │  │ helper, CLAUDE_ENV_FILE (re-sourced each cmd)   │   │
@@ -108,7 +108,7 @@ The original spec proposed a background MCP server for continuous refresh. The i
 
 4. **Legacy flat settings** — `github_app_id`, `private_key_path`, `github_installation_id` in plugin config
 
-**Private key handling**: If `GITHUB_APP_PRIVATE_KEY` contains key content (e.g., from 1Password) but no `GITHUB_APP_PRIVATE_KEY_PATH` is set, the key content is written to a secure temp file (`~/.config/agent/github-app-<app_id>.pem`, chmod 600).
+**Private key handling**: If `GITHUB_APP_PRIVATE_KEY` contains key content (e.g., from 1Password) but no `GITHUB_APP_PRIVATE_KEY_PATH` is set, the key content is written to a secure temp file (`~/.agents/${AGENT_NAME}/.config/github-app-<app_id>.pem`, chmod 600).
 
 **Token generation** (`bin/generate-token.sh`):
 
@@ -117,7 +117,7 @@ The original spec proposed a background MCP server for continuous refresh. The i
 3. Write token to file (chmod 600)
 4. Write metadata to `.meta` file (expiry, app_id, installation_id, permissions)
 
-**Runtime env file**: Written to `~/.config/agent/github-app-env` and registered via `CLAUDE_ENV_FILE` as a `source` command. This file is re-sourced before each Bash command, so token refreshes by the PreToolUse hook are picked up automatically.
+**Runtime env file**: Written to `~/.agents/${AGENT_NAME}/.config/github-app-env` and registered via `CLAUDE_ENV_FILE` as a `source` command. This file is re-sourced before each Bash command, so token refreshes by the PreToolUse hook are picked up automatically.
 
 **Git identity**: If `auto_git_config: true` (default) and git user.name/email aren't already set, the hook fetches the App's slug from the API and configures git identity as `app-slug[bot] <id+app-slug[bot]@users.noreply.github.com>`.
 
@@ -154,15 +154,15 @@ Standalone script invoked by both the PreToolUse hook (sync or background) and p
 
 ### Token Distribution
 
-**Primary mechanism**: Shared file at `~/.config/agent/github-token`
+**Primary mechanism**: Shared file at `~/.agents/${AGENT_NAME}/.config/github-token`
 
 Consumers:
 
 - **`gh` CLI**: Via `$GH_TOKEN` environment variable (set by runtime env file)
 - **`git push/pull`**: Via git credential helper (`bin/git-credential-github-app.sh`)
 - **Direct reads**: Scripts can `cat $GITHUB_TOKEN_FILE`
 
-The runtime env file (`~/.config/agent/github-app-env`) is sourced via `CLAUDE_ENV_FILE` before each Bash command, ensuring `$GH_TOKEN` and `$GITHUB_TOKEN` always reflect the latest token.
+The runtime env file (`~/.agents/${AGENT_NAME}/.config/github-app-env`) is sourced via `CLAUDE_ENV_FILE` before each Bash command, ensuring `$GH_TOKEN` and `$GITHUB_TOKEN` always reflect the latest token.
 
 **Git credential helper** (`bin/git-credential-github-app.sh`):
 
@@ -218,14 +218,14 @@ github-app:
 
   # Option 3: Legacy flat settings
   # github_app_id: "12345"
-  # private_key_path: "~/.config/agent/github-app.pem"
+  # private_key_path: "~/.agents/${AGENT_NAME}/.config/github-app.pem"
   # github_installation_id: "67890"
 
   # Auto-configure git identity from App bot account (default: true)
   auto_git_config: true
 
-  # Token file location (default: ~/.config/agent/github-token)
-  # token_file: "~/.config/agent/github-token"
+  # Token file location (default: ~/.agents/${AGENT_NAME}/.config/github-token)
+  # token_file: "~/.agents/${AGENT_NAME}/.config/github-token"
 ```
 
 Or via environment variables: `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY_PATH`, `GITHUB_INSTALLATION_ID`, `GITHUB_TOKEN_FILE`.

plugins/github-app/github-app.settings.yaml

@@ -23,7 +23,7 @@ github-app:
   #      Sources KEY=VALUE pairs from a file. Relative paths (./...)
   #      resolve against the project directory.
   #      Example: ref: "env-file://./.env.github-app"
-  #      Example: ref: "env-file://~/.config/agent/github-app.env"
+  #      Example: ref: "env-file://~/.agents/<agent-name>/.config/github-app.env"
   #
   # 2. secrets.*: Individual secret references. Each value can be:
   #    - A literal value:         secrets.github_app_id: "12345"
@@ -51,7 +51,7 @@ github-app:
 
   # --- Option 3: Legacy flat settings ---
   # github_app_id: "12345"
-  # private_key_path: "~/.config/agent/github-app.pem"
+  # private_key_path: "~/.agents/<agent-name>/.config/github-app.pem"
   # github_installation_id: "67890"
 
   # --- Other settings ---
@@ -62,5 +62,5 @@ github-app:
   # Set to false to disable.
   autoGitConfig: true
 
-  # Where to write the token (default: ~/.config/agent/github-token)
-  # tokenFile: "~/.config/agent/github-token"
+  # Where to write the token (default: ~/.agents/<agent-name>/.config/github-token)
+  # tokenFile: "~/.agents/<agent-name>/.config/github-token"

plugins/github-app/hooks/scripts/github-token-check.sh

@@ -21,9 +21,12 @@ set -euo pipefail
 
 # --- Configuration ---
 
-DEBOUNCE_FILE="${HOME}/.config/agent/github-app-last-check"
+# shellcheck source=../../lib/agent-paths.sh
+source "${CLAUDE_PLUGIN_ROOT}/lib/agent-paths.sh"
+
+DEBOUNCE_FILE="${AGENT_CONFIG_DIR}/github-app-last-check"
 DEBOUNCE_SECONDS=30  # Don't check more often than every 30 seconds
-TOKEN_FILE="${GITHUB_TOKEN_FILE:-$HOME/.config/agent/github-token}"
+TOKEN_FILE="${GITHUB_TOKEN_FILE:-${AGENT_CONFIG_DIR}/github-token}"
 META_FILE="${TOKEN_FILE}.meta"
 
 # --- Read hook input ---
@@ -88,11 +91,11 @@ uses_token() {
 
 # --- Token status check ---
 
-# Resolve the bin/lib directories relative to this script (handles both plugin and symlink cases)
-PLUGIN_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+# Resolve the bin/lib directories via CLAUDE_PLUGIN_ROOT (set by the harness for hook scripts)
+PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT}"
 source "$PLUGIN_DIR/lib/token-utils.sh"
 
-BIN_DIR="$PLUGIN_DIR/bin"
+BIN_DIR="${CLAUDE_PLUGIN_ROOT}/bin"
 
 # --- Allow helper ---
 

plugins/github-app/hooks/scripts/github-token-init.sh

@@ -23,6 +23,7 @@ set -euo pipefail
 PLUGIN_NAME="github-app"
 source "${CLAUDE_PLUGIN_ROOT}/lib/plugin-config-read.sh"
 source "${CLAUDE_PLUGIN_ROOT}/lib/hook-logging.sh"
+source "${CLAUDE_PLUGIN_ROOT}/lib/agent-paths.sh"
 
 # --- Guards ---
 
@@ -163,7 +164,7 @@ GITHUB_APP_PRIVATE_KEY_PATH="${GITHUB_APP_PRIVATE_KEY_PATH:-$(plugin_get_config
 
 if [[ -n "${GITHUB_APP_PRIVATE_KEY:-}" && -z "$GITHUB_APP_PRIVATE_KEY_PATH" ]]; then
   # Key content provided directly — write to a secure temp file
-  KEY_DIR="${HOME}/.config/agent"
+  KEY_DIR="${AGENT_CONFIG_DIR}"
   mkdir -p "$KEY_DIR"
   GITHUB_APP_PRIVATE_KEY_PATH="${KEY_DIR}/github-app-${GITHUB_APP_ID:-unknown}.pem"
   echo "$GITHUB_APP_PRIVATE_KEY" > "$GITHUB_APP_PRIVATE_KEY_PATH"
@@ -198,7 +199,7 @@ fi
 
 hook_log_step "generate-token" "Generating GitHub App installation token"
 
-TOKEN_FILE="${GITHUB_TOKEN_FILE:-$(plugin_get_config "tokenFile" "$HOME/.config/agent/github-token")}"
+TOKEN_FILE="${GITHUB_TOKEN_FILE:-$(plugin_get_config "tokenFile" "${AGENT_CONFIG_DIR}/github-token")}"
 TOKEN_FILE="${TOKEN_FILE/#\~/$HOME}"
 mkdir -p "$(dirname "$TOKEN_FILE")"
 
@@ -234,7 +235,7 @@ fi
 
 hook_log_step "write-env" "Writing runtime environment file"
 
-ENV_RUNTIME_FILE="${HOME}/.config/agent/github-app-env"
+ENV_RUNTIME_FILE="${AGENT_CONFIG_DIR}/github-app-env"
 mkdir -p "$(dirname "$ENV_RUNTIME_FILE")"
 cat > "$ENV_RUNTIME_FILE" <<ENVEOF
 # Auto-generated by github-app plugin — do not edit

plugins/github-app/lib/agent-paths.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# agent-paths.sh — Shared helper for per-agent config directory resolution
+#
+# Exports AGENT_CONFIG_DIR based on AGENT_NAME env var.
+# All github-app plugin scripts should source this instead of
+# computing the path independently.
+#
+# Usage (hooks):  source "${CLAUDE_PLUGIN_ROOT}/lib/agent-paths.sh"
+# Usage (bin/):   _self="${BASH_SOURCE[0]}"; while [ -L "$_self" ]; do _self="$(readlink -f "$_self")"; done
+#                 source "$(cd "$(dirname "$_self")/.." && pwd)/lib/agent-paths.sh"
+
+[[ -n "${_AGENT_PATHS_LOADED:-}" ]] && return 0
+_AGENT_PATHS_LOADED=1
+
+AGENT_CONFIG_DIR="${HOME}/.agents/${AGENT_NAME:-_UNKNOWN}/.config"