axconfig 1.0.0 → 2.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
 
@@ -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(
@@ -101,128 +92,134 @@ if (result.ok) {
   // result.env = { CLAUDE_CONFIG_DIR: "/tmp/my-config" }
   // result.warnings = [...]
 }
+
+// Read existing config
+const reader = getConfigReader("claude-code");
+const configDir = resolveConfigPath("claude-code"); // ~/.claude/
+
+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" });
 ```
 
 ## CLI Commands
 
-```bash
-# List agents and their auth status
-axconfig auth list
-axconfig auth list --json
-
-# 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 \
   --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)
-```
 
-## Pipeline Examples
+# Export as JSON for parsing
+axconfig create --agent claude-code --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-code 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-code deny
+# Output: bash:rm *
 
-# Count agents by status
-axconfig auth list | tail -n +2 | cut -f2 | sort | uniq -c
+axconfig get --agent claude-code 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-code 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'
-
-# Check if a specific agent is authenticated
-axconfig auth list --json | jq -e '.[] | select(.agentId == "claude-code") | .authenticated'
-```
+# Set settings (merge with existing by default)
+axconfig set --agent claude-code allow "read,glob"
+axconfig set --agent claude-code deny "bash:rm *"
+axconfig set --agent claude-code model "claude-sonnet-4-20250514"
 
-## Module Structure
+# Replace instead of merge (for allow/deny)
+axconfig set --agent claude-code allow "read,glob" --replace
 
+# Set with custom config path
+axconfig set --agent claude-code --path /tmp/cfg allow "read,glob"
 ```
-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
-```
-
-## Integration with axrun
 
-axrun imports axconfig as a dependency:
+### Get/Set Raw Config Values
 
-```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",
-});
+```bash
+# Get raw config value by dotted path
+axconfig get-raw --agent claude-code permissions.allow
+# Output: ["Read", "Glob"]
 
-if (!configResult.ok) {
-  // Handle errors
-}
+# Get raw value as JSON
+axconfig get-raw --agent claude-code permissions --format json
 
-// Spawn agent with config
-spawn(agentBin, args, { env: { ...process.env, ...configResult.env } });
+# Set raw config value (JSON or string)
+axconfig set-raw --agent claude-code permissions.allow '["Read", "Glob"]'
+axconfig set-raw --agent opencode permission.edit allow
 ```
 
-## Auth Preservation
+### Pipeline Examples
 
-A key requirement is preserving agent authentication when injecting permissions.
+```bash
+# Capture settings in shell variables
+ALLOW=$(axconfig get --agent claude-code allow)
+MODEL=$(axconfig get --agent claude-code model)
 
-### Problem
+# Extract allow rules as JSON and filter with jq
+axconfig get --agent claude-code allow --format json | jq '.'
 
-Agents store auth in their config directories. Naively overriding config paths breaks auth:
+# List all bash permissions, one per line
+axconfig get --agent claude-code allow | tr ',' '\n' | grep 'bash:'
 
-```bash
-# This breaks auth!
-CLAUDE_CONFIG_DIR=/tmp/custom claude "prompt"
-```
+# Count unique bash command prefixes
+axconfig get --agent claude-code allow \
+  | tr ',' '\n' | grep 'bash:' \
+  | cut -d: -f2 | cut -d' ' -f1 | sort | uniq -c | sort -rn
+
+# Compare permissions between agents
+diff <(axconfig get -a claude-code allow) <(axconfig get -a gemini allow)
 
-### Solution
+# Check if a specific permission exists
+axconfig get --agent claude-code allow | grep -q 'bash:git' && echo "git allowed"
 
-Each agent has a preferred method for layering config:
+# Add a new permission to existing allow list
+CURRENT=$(axconfig get --agent claude-code allow)
+axconfig set --agent claude-code allow "$CURRENT,write" --replace
+```
 
-| 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-code.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
 
@@ -235,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-code-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-code-reader.js

@@ -0,0 +1,160 @@
+/**
+ * Claude Code ConfigReader.
+ *
+ * Reads and writes Claude Code configuration from settings.json.
+ */
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+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}`,
+        };
+    }
+}
+/** Claude Code ConfigReader */
+const claudeCodeConfigReader = {
+    agentId: "claude",
+    defaultConfigDir: () => path.join(homedir(), ".claude"),
+    envVar: "CLAUDE_CONFIG_DIR",
+    readPermissions,
+    readModel,
+    writeModel,
+    readRaw,
+    writeRaw,
+    deleteRaw,
+};
+// Self-register on import
+registerConfigReader(claudeCodeConfigReader);
+export { claudeCodeConfigReader };

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

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

package/dist/agents/claude-code.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-code-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 };