axconfig 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Łukasz Jerciński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# axconfig
+
+Configuration management library and CLI for AI coding agents.
+
+## Overview
+
+axconfig is the **single source of truth** for all AI coding agent configuration logic. It can be used:
+
+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
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         axrun                                │
+│  (Agent execution: spawns agents, streams events)           │
+│                                                              │
+│  axrun -a claude-code --allow "read,bash:git *" "prompt"    │
+│                           │                                  │
+│                           ▼                                  │
+│              ┌────────────────────────┐                      │
+│              │       axconfig         │                      │
+│              │  (Config translation)  │                      │
+│              └────────────────────────┘                      │
+│                           │                                  │
+│                           ▼                                  │
+│                    { env, settings }                         │
+│                           │                                  │
+│                           ▼                                  │
+│              spawn(claude, { env })                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Core Responsibilities
+
+### Permission Parsing
+
+Unified syntax for all agents:
+
+```bash
+# Tool permissions
+read, write, edit, bash, glob, grep, web
+
+# Bash command patterns
+bash:git *
+bash:npm run build
+
+# Path restrictions (agent-dependent)
+read:src/**
+write:.env
+```
+
+### Config Translation
+
+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}`               |
+
+### Capability Validation
+
+Each agent has different capabilities:
+
+| Agent       | Tool Perms  | Bash Patterns | Path Restrictions | Can Deny Read |
+| ----------- | ----------- | ------------- | ----------------- | ------------- |
+| claude-code | ✓           | ✓             | ✓                 | ✓             |
+| codex       | ✗ (sandbox) | ✓             | ✗                 | ✗             |
+| gemini      | ✓           | ✓             | ✗                 | ✓             |
+| opencode    | ✓           | ✓             | ✗                 | ✓             |
+
+axconfig validates permissions against agent capabilities:
+
+- **Unsupported allow rules** → warning, rule dropped (safe: fewer permissions)
+- **Unsupported deny rules** → error, abort (unsafe: can't enforce restriction)
+
+## Library API
+
+```typescript
+import { parsePermissions, getConfigBuilder, buildAgentConfig } from "axconfig";
+
+// Parse CLI-style permission strings
+const permissions = parsePermissions(
+  ["read,glob,bash:git *"], // allow
+  ["bash:rm *"], // deny
+);
+
+// Build agent-specific config
+const result = buildAgentConfig({
+  agentId: "claude-code",
+  allow: "read,glob,bash:git *",
+  deny: "bash:rm *",
+  output: "/tmp/my-config", // directory for config files
+});
+
+if (result.ok) {
+  // result.env = { CLAUDE_CONFIG_DIR: "/tmp/my-config" }
+  // result.warnings = [...]
+}
+```
+
+## 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 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
+
+The CLI outputs TSV format for easy processing with standard Unix tools:
+
+```bash
+# List all agents and their auth status
+axconfig auth list
+# AGENT         STATUS          METHOD
+# claude-code   authenticated   OAuth (max)
+# codex         authenticated   ChatGPT OAuth
+# ...
+
+# Filter to show only authenticated agents
+axconfig auth list | tail -n +2 | awk -F'\t' '$2 == "authenticated"'
+
+# Count agents by status
+axconfig auth list | tail -n +2 | cut -f2 | sort | uniq -c
+
+# Extract agent names as a list
+axconfig auth list | tail -n +2 | cut -f1
+
+# 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'
+```
+
+## Module Structure
+
+```
+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:
+
+```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",
+});
+
+if (!configResult.ok) {
+  // Handle errors
+}
+
+// Spawn agent with config
+spawn(agentBin, args, { env: { ...process.env, ...configResult.env } });
+```
+
+## Auth Preservation
+
+A key requirement is preserving agent authentication when injecting permissions.
+
+### Problem
+
+Agents store auth in their config directories. Naively overriding config paths breaks auth:
+
+```bash
+# This breaks auth!
+CLAUDE_CONFIG_DIR=/tmp/custom claude "prompt"
+```
+
+### 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            |
+
+axconfig handles these differences internally.
+
+## Agent Rule
+
+Add to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+# Rule: `axconfig` Usage
+
+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.
+```
+
+## Development Status
+
+🚧 **Work in Progress**
+
+Migrating config logic from axrun to axconfig.
+
+## License
+
+MIT

package/bin/axconfig

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point that dynamically imports the compiled TypeScript.
+ *
+ * Uses top-level await to ensure module evaluation errors are handled
+ * properly. Without await, errors during import would surface as unhandled
+ * rejections instead of clean CLI failures with appropriate exit codes.
+ */
+try {
+  await import("../dist/cli.js");
+} catch (error) {
+  console.error(
+    "Failed to start axconfig:",
+    error instanceof Error ? error.message : error,
+  );
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Claude Code ConfigBuilder.
+ *
+ * Translates AxrunConfig into Claude Code's settings.json format.
+ *
+ * Claude Code supports:
+ * - Tool permissions via permissions.allow/deny
+ * - Bash patterns like "Bash(git:*)"
+ * - Path patterns like "Read(src/**)"
+ */
+import type { ConfigBuilder } from "../types.js";
+/** Claude Code ConfigBuilder */
+declare const claudeCodeConfigBuilder: ConfigBuilder;
+export { claudeCodeConfigBuilder };

package/dist/agents/claude-code.js

@@ -0,0 +1,98 @@
+/**
+ * Claude Code ConfigBuilder.
+ *
+ * Translates AxrunConfig into Claude Code's settings.json format.
+ *
+ * Claude Code supports:
+ * - Tool permissions via permissions.allow/deny
+ * - Bash patterns like "Bash(git:*)"
+ * - Path patterns like "Read(src/**)"
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { registerConfigBuilder } from "../builder.js";
+/** Claude Code tool name mapping */
+const TOOL_MAP = {
+    read: "Read",
+    write: "Write",
+    edit: "Edit",
+    bash: "Bash",
+    glob: "Glob",
+    grep: "Grep",
+    web: "WebFetch",
+};
+/** Claude Code capabilities */
+const CAPABILITIES = {
+    toolPermissions: true,
+    bashPatterns: true,
+    pathRestrictions: true,
+    canDenyRead: true,
+};
+/**
+ * Translate a permission rule to Claude Code format.
+ */
+function translateRule(rule) {
+    switch (rule.type) {
+        case "tool": {
+            return TOOL_MAP[rule.name];
+        }
+        case "bash": {
+            // Claude Code uses "Bash(pattern:*)" for command patterns
+            return `Bash(${rule.pattern}:*)`;
+        }
+        case "path": {
+            // Claude Code uses "Tool(path/**)" for path patterns
+            const toolName = rule.tool.charAt(0).toUpperCase() + rule.tool.slice(1);
+            return `${toolName}(${rule.pattern})`;
+        }
+    }
+}
+/**
+ * Build Claude Code configuration.
+ */
+function build(config, output) {
+    mkdirSync(output, { recursive: true });
+    const warnings = [];
+    const permissions = config.permissions;
+    const settingsPath = path.join(output, "settings.json");
+    // If no permissions specified, deny all
+    if (!permissions) {
+        const settings = {
+            permissions: {
+                allow: [],
+                deny: [],
+            },
+        };
+        writeFileSync(settingsPath, JSON.stringify(settings, undefined, 2));
+        return {
+            ok: true,
+            env: { CLAUDE_CONFIG_DIR: output },
+            warnings: [],
+        };
+    }
+    // Claude Code supports all permission types, so no warnings/errors needed
+    // All rules can be translated directly
+    const allowRules = permissions.allow.map((rule) => translateRule(rule));
+    const denyRules = permissions.deny.map((rule) => translateRule(rule));
+    const settings = {
+        permissions: {
+            allow: allowRules,
+            deny: denyRules,
+        },
+    };
+    writeFileSync(settingsPath, JSON.stringify(settings, undefined, 2));
+    return {
+        ok: true,
+        env: { CLAUDE_CONFIG_DIR: output },
+        warnings,
+    };
+}
+/** Claude Code ConfigBuilder */
+const claudeCodeConfigBuilder = {
+    agentId: "claude-code",
+    capabilities: CAPABILITIES,
+    build,
+};
+// Self-register on import
+registerConfigBuilder(claudeCodeConfigBuilder);
+export { claudeCodeConfigBuilder };

package/dist/agents/codex.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Codex ConfigBuilder.
+ *
+ * Translates AxrunConfig into Codex's config.toml and execpolicy rules.
+ *
+ * Codex has unique characteristics:
+ * - Uses OS-level sandbox for file access (read-only, workspace-write)
+ * - Uses execpolicy .rules files for bash command patterns
+ * - CANNOT deny read access (sandbox always allows reads)
+ * - Does NOT support path restrictions
+ */
+import type { ConfigBuilder } from "../types.js";
+/** Codex ConfigBuilder */
+declare const codexConfigBuilder: ConfigBuilder;
+export { codexConfigBuilder };

package/dist/agents/codex.js

@@ -0,0 +1,164 @@
+/**
+ * Codex ConfigBuilder.
+ *
+ * Translates AxrunConfig into Codex's config.toml and execpolicy rules.
+ *
+ * Codex has unique characteristics:
+ * - Uses OS-level sandbox for file access (read-only, workspace-write)
+ * - Uses execpolicy .rules files for bash command patterns
+ * - CANNOT deny read access (sandbox always allows reads)
+ * - Does NOT support path restrictions
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { registerConfigBuilder } from "../builder.js";
+/** Codex capabilities */
+const CAPABILITIES = {
+    toolPermissions: false, // Uses sandbox mode instead
+    bashPatterns: true,
+    pathRestrictions: false,
+    canDenyRead: false, // Sandbox always allows reads
+};
+/**
+ * Infer sandbox mode from permissions.
+ *
+ * - If write or edit is allowed → workspace-write
+ * - Otherwise → read-only
+ */
+function inferSandboxMode(permissions) {
+    const allowsWrite = permissions.allow.some((r) => r.type === "tool" && (r.name === "write" || r.name === "edit"));
+    return allowsWrite ? "workspace-write" : "read-only";
+}
+/**
+ * Generate Starlark prefix_rule for execpolicy.
+ *
+ * @example
+ * generatePrefixRule("git", "status", "allow")
+ * // Returns: prefix_rule(pattern = ["git", "status"], decision = "allow")
+ */
+function generatePrefixRule(pattern, decision) {
+    // Split the pattern into tokens
+    // "git status" → ["git", "status"]
+    // "npm run build" → ["npm", "run", "build"]
+    const tokens = pattern.trim().split(/\s+/u);
+    // Handle wildcards at the end
+    // "git *" → pattern = ["git"], which matches all git subcommands
+    const filteredTokens = tokens.filter((t) => t !== "*");
+    const patternString = JSON.stringify(filteredTokens);
+    return `prefix_rule(pattern = ${patternString}, decision = "${decision}")`;
+}
+/**
+ * Build Codex configuration.
+ */
+function build(config, output) {
+    mkdirSync(output, { recursive: true });
+    const warnings = [];
+    const errors = [];
+    const permissions = config.permissions;
+    // Check for unsupported rules
+    if (permissions) {
+        // Check for --deny "read" which is not possible in Codex
+        for (const rule of permissions.deny) {
+            if (rule.type === "tool" && rule.name === "read") {
+                errors.push({
+                    rule,
+                    reason: "Codex sandbox mode always permits file reads",
+                    suggestions: [
+                        "Use a different agent that supports denying reads (e.g., claude-code)",
+                        'Remove the --deny "read" rule',
+                    ],
+                });
+            }
+            // Path restrictions not supported
+            if (rule.type === "path") {
+                errors.push({
+                    rule,
+                    reason: "Codex does not support path restrictions",
+                    suggestions: [
+                        `Use "${rule.tool}" to deny all ${rule.tool} operations`,
+                        "Use a different agent that supports path restrictions (e.g., claude-code)",
+                    ],
+                });
+            }
+        }
+        // Path restrictions in allow rules - warn and drop
+        for (const rule of permissions.allow) {
+            if (rule.type === "path") {
+                warnings.push({
+                    rule,
+                    reason: "Codex does not support path restrictions",
+                    suggestions: [
+                        `Use "${rule.tool}" to allow all ${rule.tool} operations`,
+                        "Remove the path restriction",
+                    ],
+                });
+            }
+        }
+        // Tool permissions other than read/write/edit - warn as Codex uses sandbox
+        const nonFileTools = permissions.allow.filter((r) => r.type === "tool" &&
+            !["read", "write", "edit", "bash"].includes(r.name));
+        for (const rule of nonFileTools) {
+            if (rule.type === "tool") {
+                warnings.push({
+                    rule,
+                    reason: `Codex does not have a dedicated "${rule.name}" tool permission`,
+                    suggestions: [
+                        `Tool "${rule.name}" may not be available in Codex`,
+                        "Check Codex documentation for available tools",
+                    ],
+                });
+            }
+        }
+    }
+    // If there are errors, abort
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // Create CODEX_HOME directory structure
+    const rulesDirectory = path.join(output, "rules");
+    mkdirSync(rulesDirectory, { recursive: true });
+    // Infer sandbox mode
+    const sandboxMode = permissions ? inferSandboxMode(permissions) : "read-only";
+    // Generate config.toml
+    const configToml = `# Generated by axconfig
+approval_policy = "never"
+sandbox_mode = "${sandboxMode}"
+`;
+    writeFileSync(path.join(output, "config.toml"), configToml);
+    // Generate execpolicy rules
+    const rules = ["# Generated by axconfig"];
+    if (permissions) {
+        // Collect bash patterns
+        const allowBash = permissions.allow
+            .filter((r) => r.type === "bash")
+            .map((r) => r.pattern);
+        const denyBash = permissions.deny
+            .filter((r) => r.type === "bash")
+            .map((r) => r.pattern);
+        // Generate allow rules
+        for (const pattern of allowBash) {
+            rules.push(generatePrefixRule(pattern, "allow"));
+        }
+        // Generate deny rules
+        for (const pattern of denyBash) {
+            rules.push(generatePrefixRule(pattern, "forbidden"));
+        }
+    }
+    // Write rules file
+    const rulesPath = path.join(rulesDirectory, "axconfig.rules");
+    writeFileSync(rulesPath, rules.join("\n"));
+    return {
+        ok: true,
+        env: { CODEX_HOME: output },
+        warnings,
+    };
+}
+/** Codex ConfigBuilder */
+const codexConfigBuilder = {
+    agentId: "codex",
+    capabilities: CAPABILITIES,
+    build,
+};
+// Self-register on import
+registerConfigBuilder(codexConfigBuilder);
+export { codexConfigBuilder };

package/dist/agents/gemini.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Gemini CLI ConfigBuilder.
+ *
+ * Translates AxrunConfig into Gemini CLI's TOML policy format.
+ *
+ * Gemini CLI supports:
+ * - Tool permissions via [[rule]] with toolName
+ * - Bash patterns via commandPrefix
+ * - Does NOT support path restrictions
+ */
+import type { ConfigBuilder } from "../types.js";
+/** Gemini CLI ConfigBuilder */
+declare const geminiConfigBuilder: ConfigBuilder;
+export { geminiConfigBuilder };