axconfig 1.1.0 → 3.0.0

package/README.md

@@ -1,38 +1,24 @@
 # axconfig
 
-Configuration management library and CLI for AI coding agents.
+Unified configuration management for AI coding agents — common API for permissions, settings, and config across Claude Code, Codex, Gemini CLI, and OpenCode.
 
 ## Overview
 
-axconfig is the **single source of truth** for all AI coding agent configuration logic. It can be used:
+Different AI coding agents each have their own config formats, permission syntaxes, and settings locations. If you want to control what an agent can do or configure its behavior, you'd need to learn each agent's specific configuration format and file locations.
 
-1. **As a library** - imported by [axrun](https://github.com/anthropics/axrun) to build agent configs programmatically
-2. **As a CLI** - standalone tool for managing, inspecting, and creating agent configs
+axconfig solves this by providing:
 
-## Architecture
+1. **Unified permission syntax** — One way to express permissions (`--allow read,bash:git *`) that works across all agents
+2. **Common config access** — Get and set configuration properties using a consistent API, regardless of agent
+3. **Translation to agent-specific formats** — Converts unified config into whatever format each agent expects
+4. **Capability validation** — Knows what each agent supports and warns/errors appropriately
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                         axrun                                │
-│  (Agent execution: spawns agents, streams events)           │
-│                                                              │
-│  axrun -a claude-code --allow "read,bash:git *" "prompt"    │
-│                           │                                  │
-│                           ▼                                  │
-│              ┌────────────────────────┐                      │
-│              │       axconfig         │                      │
-│              │  (Config translation)  │                      │
-│              └────────────────────────┘                      │
-│                           │                                  │
-│                           ▼                                  │
-│                    { env, settings }                         │
-│                           │                                  │
-│                           ▼                                  │
-│              spawn(claude, { env })                          │
-└─────────────────────────────────────────────────────────────┘
-```
+It can be used:
+
+- **As a library** — integrate into your own tools and scripts
+- **As a CLI** — standalone tool for managing agent configs
 
-## Core Responsibilities
+## Core Functionality
 
 ### Permission Parsing
 
@@ -55,23 +41,23 @@ write:.env
 
 Translates unified permissions to agent-specific formats:
 
-| Agent       | Output Format                                             |
-| ----------- | --------------------------------------------------------- |
-| claude-code | JSON `settings.json` with `permissions.allow/deny` arrays |
-| codex       | TOML `config.toml` + Starlark `.rules` files              |
-| gemini      | TOML policy files with `[[rule]]` entries                 |
-| opencode    | JSON with `permission.{edit,bash,webfetch}`               |
+| Agent    | Output Format                                             |
+| -------- | --------------------------------------------------------- |
+| claude   | JSON `settings.json` with `permissions.allow/deny` arrays |
+| codex    | TOML `config.toml` + Starlark `.rules` files              |
+| gemini   | TOML policy files with `[[rule]]` entries                 |
+| opencode | JSON with `permission.{edit,bash,webfetch}`               |
 
 ### Capability Validation
 
 Each agent has different capabilities:
 
-| Agent       | Tool Perms  | Bash Patterns | Path Restrictions | Can Deny Read |
-| ----------- | ----------- | ------------- | ----------------- | ------------- |
-| claude-code | ✓           | ✓             | ✓                 | ✓             |
-| codex       | ✗ (sandbox) | ✓             | ✗                 | ✗             |
-| gemini      | ✓           | ✓             | ✗                 | ✓             |
-| opencode    | ✓           | ✓             | ✗                 | ✓             |
+| Agent    | Tool Perms  | Bash Patterns | Path Restrictions | Can Deny Read |
+| -------- | ----------- | ------------- | ----------------- | ------------- |
+| claude   | ✓           | ✓             | ✓                 | ✓             |
+| codex    | ✗ (sandbox) | ✓             | ✗                 | ✗             |
+| gemini   | ✓           | ✓             | ✗                 | ✓             |
+| opencode | ✓           | ✓             | ✗                 | ✓             |
 
 axconfig validates permissions against agent capabilities:
 
@@ -81,7 +67,12 @@ axconfig validates permissions against agent capabilities:
 ## Library API
 
 ```typescript
-import { parsePermissions, getConfigBuilder, buildAgentConfig } from "axconfig";
+import {
+  buildAgentConfig,
+  getConfigReader,
+  parsePermissions,
+  resolveConfigPath,
+} from "axconfig";
 
 // Parse CLI-style permission strings
 const permissions = parsePermissions(
@@ -91,7 +82,7 @@ const permissions = parsePermissions(
 
 // Build agent-specific config
 const result = buildAgentConfig({
-  agentId: "claude-code",
+  agentId: "claude",
   allow: "read,glob,bash:git *",
   deny: "bash:rm *",
   output: "/tmp/my-config", // directory for config files
@@ -101,136 +92,134 @@ if (result.ok) {
   // result.env = { CLAUDE_CONFIG_DIR: "/tmp/my-config" }
   // result.warnings = [...]
 }
-```
 
-## CLI Commands
+// Read existing config
+const reader = getConfigReader("claude");
+const configDir = resolveConfigPath("claude"); // ~/.claude/
 
-```bash
-# List agents and their auth status
-axconfig auth list
-axconfig auth list --json
+const perms = reader.readPermissions(configDir);
+if (perms.ok && perms.value) {
+  console.log(perms.value.allow); // PermissionRule[]
+}
+
+// Read/write raw config values
+const raw = reader.readRaw(configDir, "permissions.allow");
+reader.writeRaw(configDir, "customSetting", { foo: "bar" });
+```
 
-# Get access token for an agent (outputs raw token for piping)
-axconfig auth token --agent claude-code
+## CLI Commands
 
-# Export credentials to encrypted file
-axconfig auth export --agent claude-code --output creds.json
-axconfig auth export --agent claude-code --output creds.json --no-password
+### Create Config
 
+```bash
 # Create config with permissions (outputs env vars)
-axconfig create --agent claude-code --output /tmp/config \
+axconfig create --agent claude --output /tmp/config \
   --allow "read,glob,bash:git *" \
   --deny "bash:rm *"
 
-# Create config with exported credentials
-axconfig create --agent claude-code --output /tmp/config \
-  --allow read \
-  --with-credentials creds.json
-
 # Export for shell usage
-eval $(axconfig create --agent claude-code --output /tmp/config --allow read)
-```
+eval $(axconfig create --agent claude --output /tmp/config --allow read)
 
-## Pipeline Examples
+# Export as JSON for parsing
+axconfig create --agent claude --output /tmp/cfg --allow read --format json | jq '.env'
+```
 
-The CLI outputs TSV format for easy processing with standard Unix tools:
+### Get/Set Unified Settings
 
 ```bash
-# List all agents and their auth status
-axconfig auth list
-# AGENT         STATUS          METHOD
-# claude-code   authenticated   OAuth (max)
-# codex         authenticated   ChatGPT OAuth
-# ...
+# Get current settings (uses agent's default config location)
+axconfig get --agent claude allow
+# Output: read,glob,bash:git *
 
-# Filter to show only authenticated agents
-axconfig auth list | tail -n +2 | awk -F'\t' '$2 == "authenticated"'
+axconfig get --agent claude deny
+# Output: bash:rm *
 
-# Count agents by status
-axconfig auth list | tail -n +2 | cut -f2 | sort | uniq -c
+axconfig get --agent claude model
+# Output: sonnet
 
-# Extract agent names as a list
-axconfig auth list | tail -n +2 | cut -f1
+# Get settings as JSON
+axconfig get --agent claude allow --format json
+# Output: ["Read", "Glob", {"Bash": {"command": "git", "args": "*"}}]
 
-# Export config as JSON and extract specific fields with jq
-axconfig create --agent claude-code --output /tmp/cfg --allow read --format json | jq '.env'
+# Set settings (merge with existing by default)
+axconfig set --agent claude allow "read,glob"
+axconfig set --agent claude deny "bash:rm *"
+axconfig set --agent claude model "claude-sonnet-4-20250514"
 
-# Check if a specific agent is authenticated
-axconfig auth list --json | jq -e '.[] | select(.agentId == "claude-code") | .authenticated'
+# Replace instead of merge (for allow/deny)
+axconfig set --agent claude allow "read,glob" --replace
 
-# Check Claude Code usage via OAuth endpoint
-curl -s -H "Authorization: Bearer $(axconfig auth token --agent claude-code)" \
-  -H "anthropic-beta: oauth-2025-04-20" \
-  https://api.anthropic.com/api/oauth/usage | jq .
+# Set with custom config path
+axconfig set --agent claude --path /tmp/cfg allow "read,glob"
 ```
 
-## Module Structure
+### Get/Set Raw Config Values
 
-```
-src/
-├── types.ts                # PermissionRule, AxrunConfig, BuildResult, etc.
-├── parse-permissions.ts    # parseRule, parseRuleList, parsePermissions
-├── builder.ts              # ConfigBuilder registry
-├── build-agent-config.ts   # High-level buildAgentConfig function
-├── check-auth.ts           # Auth status detection for agents
-├── extract-credentials.ts  # Credential extraction for export
-├── crypto.ts               # AES-256-GCM encryption for credentials
-├── cli.ts                  # CLI entry point
-└── agents/
-    ├── claude-code.ts      # Claude Code config builder
-    ├── codex.ts            # Codex config builder
-    ├── gemini.ts           # Gemini CLI config builder
-    └── opencode.ts         # OpenCode config builder
-```
+```bash
+# Get raw config value by dotted path
+axconfig get-raw --agent claude permissions.allow
+# Output: ["Read", "Glob"]
 
-## Integration with axrun
+# Get raw value as JSON
+axconfig get-raw --agent claude permissions --format json
 
-axrun imports axconfig as a dependency:
+# Set raw config value (JSON or string)
+axconfig set-raw --agent claude permissions.allow '["Read", "Glob"]'
+axconfig set-raw --agent opencode permission.edit allow
+```
 
-```typescript
-// In axrun/src/cli.ts
-import { buildAgentConfig } from "axconfig";
-
-const configResult = buildAgentConfig({
-  agentId: options.agent,
-  allow: options.allow,
-  deny: options.deny,
-  output: "/tmp/axrun-config",
-});
+### Pipeline Examples
 
-if (!configResult.ok) {
-  // Handle errors
-}
+```bash
+# Capture settings in shell variables
+ALLOW=$(axconfig get --agent claude allow)
+MODEL=$(axconfig get --agent claude model)
 
-// Spawn agent with config
-spawn(agentBin, args, { env: { ...process.env, ...configResult.env } });
-```
+# Extract allow rules as JSON and filter with jq
+axconfig get --agent claude allow --format json | jq '.'
 
-## Auth Preservation
+# List all bash permissions, one per line
+axconfig get --agent claude allow | tr ',' '\n' | grep 'bash:'
 
-A key requirement is preserving agent authentication when injecting permissions.
+# Count unique bash command prefixes
+axconfig get --agent claude allow \
+  | tr ',' '\n' | grep 'bash:' \
+  | cut -d: -f2 | cut -d' ' -f1 | sort | uniq -c | sort -rn
 
-### Problem
+# Compare permissions between agents
+diff <(axconfig get -a claude allow) <(axconfig get -a gemini allow)
 
-Agents store auth in their config directories. Naively overriding config paths breaks auth:
+# Check if a specific permission exists
+axconfig get --agent claude allow | grep -q 'bash:git' && echo "git allowed"
 
-```bash
-# This breaks auth!
-CLAUDE_CONFIG_DIR=/tmp/custom claude "prompt"
+# Add a new permission to existing allow list
+CURRENT=$(axconfig get --agent claude allow)
+axconfig set --agent claude allow "$CURRENT,write" --replace
 ```
 
-### Solution
-
-Each agent has a preferred method for layering config:
-
-| Agent       | Method                                               |
-| ----------- | ---------------------------------------------------- |
-| claude-code | `--settings <file>` flag merges with existing config |
-| codex       | `CODEX_HOME` with copied/symlinked auth files        |
-| gemini      | `GEMINI_CLI_SYSTEM_SETTINGS_PATH` for settings       |
-| opencode    | `OPENCODE_CONFIG` points to merged config            |
+## Module Structure
 
-axconfig handles these differences internally.
+```
+src/
+├── types.ts                # PermissionRule, ConfigReader, BuildResult, etc.
+├── parse-permissions.ts    # parseRule, parseRuleList, parsePermissions
+├── builder.ts              # ConfigBuilder registry
+├── reader.ts               # ConfigReader registry
+├── resolve-config-path.ts  # Resolve agent config directory
+├── build-agent-config.ts   # High-level buildAgentConfig function
+├── cli.ts                  # CLI entry point
+├── commands/
+│   ├── create.ts           # Create command handler
+│   ├── get.ts              # Get unified settings
+│   ├── set.ts              # Set unified settings
+│   ├── get-raw.ts          # Get raw config values
+│   └── set-raw.ts          # Set raw config values
+└── agents/
+    ├── claude.ts           # Claude Code config builder + reader
+    ├── codex.ts            # Codex config builder + reader
+    ├── gemini.ts           # Gemini CLI config builder + reader
+    └── opencode.ts         # OpenCode config builder + reader
+```
 
 ## Agent Rule
 
@@ -243,15 +232,9 @@ Run `npx -y axconfig --help` to learn available options.
 
 Use `axconfig` to manage AI agent configurations with unified permission syntax.
 It translates `--allow` and `--deny` rules to agent-specific formats (Claude Code,
-Codex, Gemini CLI, OpenCode) and handles auth preservation automatically.
+Codex, Gemini CLI, OpenCode).
 ```
 
-## Development Status
-
-🚧 **Work in Progress**
-
-Migrating config logic from axrun to axconfig.
-
 ## License
 
 MIT

package/dist/agents/claude-reader.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Claude Code ConfigReader.
+ *
+ * Reads and writes Claude Code configuration from settings.json.
+ */
+import type { ConfigReader } from "../types.js";
+/** Claude Code ConfigReader */
+declare const claudeCodeConfigReader: ConfigReader;
+export { claudeCodeConfigReader };

package/dist/agents/claude-reader.js

@@ -0,0 +1,164 @@
+/**
+ * Claude Code ConfigReader.
+ *
+ * Reads and writes Claude Code configuration from settings.json.
+ */
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { getAgentPathInfo } from "axshared";
+import { atomicWriteFileSync } from "../atomic-write.js";
+import { registerConfigReader } from "../reader.js";
+import { createJsonConfigOperations, readJsonConfig, } from "../read-write-json-config.js";
+/** Reverse mapping from Claude Code tool names to canonical names */
+const REVERSE_TOOL_MAP = {
+    Read: "read",
+    Write: "write",
+    Edit: "edit",
+    Bash: "bash",
+    Glob: "glob",
+    Grep: "grep",
+    WebFetch: "web",
+    WebSearch: "web",
+};
+/** Path-restricted tools (lowercase) */
+const PATH_TOOLS = new Set(["read", "write", "edit"]);
+/**
+ * Get the settings.json path for a config directory.
+ */
+function getSettingsPath(configDirectory) {
+    return path.join(configDirectory, "settings.json");
+}
+/**
+ * Read and parse settings.json, returning empty object if not found.
+ */
+function readSettings(configDirectory) {
+    return readJsonConfig(getSettingsPath(configDirectory));
+}
+// Create shared raw config operations
+const { readRaw, writeRaw, deleteRaw } = createJsonConfigOperations(getSettingsPath, "Claude Code");
+/**
+ * Parse a Claude Code rule string back to unified format.
+ */
+function parseClaudeRule(rule) {
+    // Check for pattern format: "Tool(pattern)"
+    const parenIndex = rule.indexOf("(");
+    if (parenIndex > 0 && rule.endsWith(")")) {
+        const toolName = rule.slice(0, parenIndex);
+        const pattern = rule.slice(parenIndex + 1, -1);
+        // Bash pattern: "Bash(git:*)" → pattern is "git:*", we want "git"
+        if (toolName === "Bash") {
+            const bashPattern = pattern.endsWith(":*")
+                ? pattern.slice(0, -2)
+                : pattern;
+            return { type: "bash", pattern: bashPattern };
+        }
+        // Path pattern: "Read(src/**)" → tool is "read", pattern is "src/**"
+        const canonicalTool = REVERSE_TOOL_MAP[toolName];
+        if (canonicalTool && PATH_TOOLS.has(canonicalTool)) {
+            return {
+                type: "path",
+                tool: canonicalTool,
+                pattern,
+            };
+        }
+        return undefined;
+    }
+    // Simple tool name: "Read" → { type: "tool", name: "read" }
+    const canonicalTool = REVERSE_TOOL_MAP[rule];
+    if (canonicalTool) {
+        return { type: "tool", name: canonicalTool };
+    }
+    return undefined;
+}
+/**
+ * Read permissions from Claude Code config.
+ */
+function readPermissions(configDirectory) {
+    try {
+        const settings = readSettings(configDirectory);
+        const permissions = settings.permissions;
+        if (!permissions) {
+            return { ok: true, value: undefined };
+        }
+        const allowRules = (permissions.allow ?? [])
+            .map((rule) => parseClaudeRule(rule))
+            .filter((rule) => rule !== undefined);
+        const denyRules = (permissions.deny ?? [])
+            .map((rule) => parseClaudeRule(rule))
+            .filter((rule) => rule !== undefined);
+        const config = {
+            allow: allowRules,
+            deny: denyRules,
+        };
+        return { ok: true, value: config };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: `Failed to read Claude Code config: ${message}`,
+        };
+    }
+}
+/**
+ * Read model from Claude Code config.
+ * Returns undefined when no model is explicitly configured.
+ */
+function readModel(configDirectory) {
+    try {
+        const settings = readSettings(configDirectory);
+        const model = settings.model;
+        if (model === undefined || model === null) {
+            return { ok: true, value: undefined };
+        }
+        if (typeof model !== "string") {
+            return { ok: false, error: "Model value is not a string" };
+        }
+        return { ok: true, value: model };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: `Failed to read Claude Code model: ${message}`,
+        };
+    }
+}
+/**
+ * Write model to Claude Code config.
+ */
+function writeModel(configDirectory, model) {
+    try {
+        mkdirSync(configDirectory, { recursive: true });
+        const settings = readSettings(configDirectory);
+        settings.model = model;
+        atomicWriteFileSync(getSettingsPath(configDirectory), JSON.stringify(settings, undefined, 2));
+        return { ok: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: `Failed to write Claude Code model: ${message}`,
+        };
+    }
+}
+// Get path info from axshared (single source of truth)
+const pathInfo = getAgentPathInfo("claude");
+/** Claude Code ConfigReader */
+const claudeCodeConfigReader = {
+    agentId: "claude",
+    defaultConfigDir: pathInfo.defaultConfigDir,
+    envVar: pathInfo.envVar,
+    subdirectory: pathInfo.subdirectory,
+    buildRuntimeEnvironment: pathInfo.buildRuntimeEnvironment,
+    readPermissions,
+    readModel,
+    writeModel,
+    readRaw,
+    writeRaw,
+    deleteRaw,
+};
+// Self-register on import
+registerConfigReader(claudeCodeConfigReader);
+export { claudeCodeConfigReader };

package/dist/agents/{claude-code.d.ts → claude.d.ts}

@@ -9,6 +9,7 @@
  * - Path patterns like "Read(src/**)"
  */
 import type { ConfigBuilder } from "../types.js";
+export { claudeCodeConfigReader } from "./claude-reader.js";
 /** Claude Code ConfigBuilder */
 declare const claudeCodeConfigBuilder: ConfigBuilder;
 export { claudeCodeConfigBuilder };

package/dist/agents/{claude-code.js → claude.js}

@@ -8,9 +8,12 @@
  * - Bash patterns like "Bash(git:*)"
  * - Path patterns like "Read(src/**)"
  */
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { atomicWriteFileSync } from "../atomic-write.js";
 import { registerConfigBuilder } from "../builder.js";
+// Re-export reader
+export { claudeCodeConfigReader } from "./claude-reader.js";
 /** Claude Code tool name mapping */
 const TOOL_MAP = {
     read: "Read",
@@ -47,23 +50,45 @@ function translateRule(rule) {
         }
     }
 }
+/**
+ * Read existing settings.json, returning empty object if not found.
+ * Throws if file exists but contains invalid JSON to prevent data loss.
+ */
+function readExistingSettings(settingsPath) {
+    if (!existsSync(settingsPath)) {
+        return {};
+    }
+    try {
+        const content = readFileSync(settingsPath, "utf8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse existing settings at ${settingsPath}: ${message}`);
+    }
+}
 /**
  * Build Claude Code configuration.
+ *
+ * Preserves existing settings (model, env, etc.) and only updates permissions.
  */
 function build(config, output) {
     mkdirSync(output, { recursive: true });
     const warnings = [];
     const permissions = config.permissions;
     const settingsPath = path.join(output, "settings.json");
+    // Read existing settings to preserve non-permission fields
+    const existingSettings = readExistingSettings(settingsPath);
     // If no permissions specified, deny all
     if (!permissions) {
         const settings = {
+            ...existingSettings,
             permissions: {
                 allow: [],
                 deny: [],
             },
         };
-        writeFileSync(settingsPath, JSON.stringify(settings, undefined, 2));
+        atomicWriteFileSync(settingsPath, JSON.stringify(settings, undefined, 2));
         return {
             ok: true,
             env: { CLAUDE_CONFIG_DIR: output },
@@ -75,12 +100,13 @@ function build(config, output) {
     const allowRules = permissions.allow.map((rule) => translateRule(rule));
     const denyRules = permissions.deny.map((rule) => translateRule(rule));
     const settings = {
+        ...existingSettings,
         permissions: {
             allow: allowRules,
             deny: denyRules,
         },
     };
-    writeFileSync(settingsPath, JSON.stringify(settings, undefined, 2));
+    atomicWriteFileSync(settingsPath, JSON.stringify(settings, undefined, 2));
     return {
         ok: true,
         env: { CLAUDE_CONFIG_DIR: output },
@@ -89,7 +115,7 @@ function build(config, output) {
 }
 /** Claude Code ConfigBuilder */
 const claudeCodeConfigBuilder = {
-    agentId: "claude-code",
+    agentId: "claude",
     capabilities: CAPABILITIES,
     build,
 };

package/dist/agents/codex-reader.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Codex ConfigReader.
+ *
+ * Reads and writes Codex configuration from config.toml and .rules files.
+ */
+import type { ConfigReader } from "../types.js";
+/** Codex ConfigReader */
+declare const codexConfigReader: ConfigReader;
+export { codexConfigReader };