axconfig 2.0.0 → 3.0.0

package/README.md

@@ -41,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:
 
@@ -82,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
@@ -94,8 +94,8 @@ if (result.ok) {
 }
 
 // Read existing config
-const reader = getConfigReader("claude-code");
-const configDir = resolveConfigPath("claude-code"); // ~/.claude/
+const reader = getConfigReader("claude");
+const configDir = resolveConfigPath("claude"); // ~/.claude/
 
 const perms = reader.readPermissions(configDir);
 if (perms.ok && perms.value) {
@@ -113,58 +113,58 @@ reader.writeRaw(configDir, "customSetting", { foo: "bar" });
 
 ```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 *"
 
 # 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)
 
 # Export as JSON for parsing
-axconfig create --agent claude-code --output /tmp/cfg --allow read --format json | jq '.env'
+axconfig create --agent claude --output /tmp/cfg --allow read --format json | jq '.env'
 ```
 
 ### Get/Set Unified Settings
 
 ```bash
 # Get current settings (uses agent's default config location)
-axconfig get --agent claude-code allow
+axconfig get --agent claude allow
 # Output: read,glob,bash:git *
 
-axconfig get --agent claude-code deny
+axconfig get --agent claude deny
 # Output: bash:rm *
 
-axconfig get --agent claude-code model
+axconfig get --agent claude model
 # Output: sonnet
 
 # Get settings as JSON
-axconfig get --agent claude-code allow --format json
+axconfig get --agent claude allow --format json
 # Output: ["Read", "Glob", {"Bash": {"command": "git", "args": "*"}}]
 
 # 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"
+axconfig set --agent claude allow "read,glob"
+axconfig set --agent claude deny "bash:rm *"
+axconfig set --agent claude model "claude-sonnet-4-20250514"
 
 # Replace instead of merge (for allow/deny)
-axconfig set --agent claude-code allow "read,glob" --replace
+axconfig set --agent claude allow "read,glob" --replace
 
 # Set with custom config path
-axconfig set --agent claude-code --path /tmp/cfg allow "read,glob"
+axconfig set --agent claude --path /tmp/cfg allow "read,glob"
 ```
 
 ### Get/Set Raw Config Values
 
 ```bash
 # Get raw config value by dotted path
-axconfig get-raw --agent claude-code permissions.allow
+axconfig get-raw --agent claude permissions.allow
 # Output: ["Read", "Glob"]
 
 # Get raw value as JSON
-axconfig get-raw --agent claude-code permissions --format json
+axconfig get-raw --agent claude permissions --format json
 
 # Set raw config value (JSON or string)
-axconfig set-raw --agent claude-code permissions.allow '["Read", "Glob"]'
+axconfig set-raw --agent claude permissions.allow '["Read", "Glob"]'
 axconfig set-raw --agent opencode permission.edit allow
 ```
 
@@ -172,29 +172,29 @@ axconfig set-raw --agent opencode permission.edit allow
 
 ```bash
 # Capture settings in shell variables
-ALLOW=$(axconfig get --agent claude-code allow)
-MODEL=$(axconfig get --agent claude-code model)
+ALLOW=$(axconfig get --agent claude allow)
+MODEL=$(axconfig get --agent claude model)
 
 # Extract allow rules as JSON and filter with jq
-axconfig get --agent claude-code allow --format json | jq '.'
+axconfig get --agent claude allow --format json | jq '.'
 
 # List all bash permissions, one per line
-axconfig get --agent claude-code allow | tr ',' '\n' | grep 'bash:'
+axconfig get --agent claude allow | tr ',' '\n' | grep 'bash:'
 
 # Count unique bash command prefixes
-axconfig get --agent claude-code allow \
+axconfig get --agent claude 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)
+diff <(axconfig get -a claude allow) <(axconfig get -a gemini allow)
 
 # Check if a specific permission exists
-axconfig get --agent claude-code allow | grep -q 'bash:git' && echo "git allowed"
+axconfig get --agent claude allow | grep -q 'bash:git' && echo "git allowed"
 
 # Add a new permission to existing allow list
-CURRENT=$(axconfig get --agent claude-code allow)
-axconfig set --agent claude-code allow "$CURRENT,write" --replace
+CURRENT=$(axconfig get --agent claude allow)
+axconfig set --agent claude allow "$CURRENT,write" --replace
 ```
 
 ## Module Structure
@@ -215,7 +215,7 @@ src/
 │   ├── get-raw.ts          # Get raw config values
 │   └── set-raw.ts          # Set raw config values
 └── agents/
-    ├── claude-code.ts      # Claude Code config builder + reader
+    ├── 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

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

@@ -4,8 +4,8 @@
  * 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 { getAgentPathInfo } from "axshared";
 import { atomicWriteFileSync } from "../atomic-write.js";
 import { registerConfigReader } from "../reader.js";
 import { createJsonConfigOperations, readJsonConfig, } from "../read-write-json-config.js";
@@ -143,11 +143,15 @@ function writeModel(configDirectory, model) {
         };
     }
 }
+// Get path info from axshared (single source of truth)
+const pathInfo = getAgentPathInfo("claude");
 /** Claude Code ConfigReader */
 const claudeCodeConfigReader = {
     agentId: "claude",
-    defaultConfigDir: () => path.join(homedir(), ".claude"),
-    envVar: "CLAUDE_CONFIG_DIR",
+    defaultConfigDir: pathInfo.defaultConfigDir,
+    envVar: pathInfo.envVar,
+    subdirectory: pathInfo.subdirectory,
+    buildRuntimeEnvironment: pathInfo.buildRuntimeEnvironment,
     readPermissions,
     readModel,
     writeModel,

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

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

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

@@ -13,7 +13,7 @@ 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";
+export { claudeCodeConfigReader } from "./claude-reader.js";
 /** Claude Code tool name mapping */
 const TOOL_MAP = {
     read: "Read",

package/dist/agents/codex-reader.js

@@ -4,9 +4,9 @@
  * Reads and writes Codex configuration from config.toml and .rules files.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import path from "node:path";
 import TOML from "@iarna/toml";
+import { getAgentPathInfo } from "axshared";
 import { atomicWriteFileSync } from "../atomic-write.js";
 import { registerConfigReader } from "../reader.js";
 import { createTomlConfigOperations, readTomlConfig, } from "../read-write-toml-config.js";
@@ -145,11 +145,15 @@ function writeModel(configDirectory, model) {
         return { ok: false, error: `Failed to write Codex model: ${message}` };
     }
 }
+// Get path info from axshared (single source of truth)
+const pathInfo = getAgentPathInfo("codex");
 /** Codex ConfigReader */
 const codexConfigReader = {
     agentId: "codex",
-    defaultConfigDir: () => path.join(homedir(), ".codex"),
-    envVar: "CODEX_HOME",
+    defaultConfigDir: pathInfo.defaultConfigDir,
+    envVar: pathInfo.envVar,
+    subdirectory: pathInfo.subdirectory,
+    buildRuntimeEnvironment: pathInfo.buildRuntimeEnvironment,
     readPermissions,
     readModel,
     writeModel,

package/dist/agents/codex.js

@@ -68,7 +68,7 @@ function build(config, output) {
                     rule,
                     reason: "Codex sandbox mode always permits file reads",
                     suggestions: [
-                        "Use a different agent that supports denying reads (e.g., claude-code)",
+                        "Use a different agent that supports denying reads (e.g., claude)",
                         'Remove the --deny "read" rule',
                     ],
                 });
@@ -80,7 +80,7 @@ function build(config, output) {
                     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)",
+                        "Use a different agent that supports path restrictions (e.g., claude)",
                     ],
                 });
             }

package/dist/agents/copilot-reader.js

@@ -8,33 +8,12 @@
  * - Does NOT support tool permissions in the axconfig sense
  */
 import { mkdirSync } from "node:fs";
-import { homedir } from "node:os";
 import path from "node:path";
+import { getAgentPathInfo } from "axshared";
 import { atomicWriteFileSync } from "../atomic-write.js";
 import { deleteByPath, getByPath } from "../object-path.js";
 import { registerConfigReader } from "../reader.js";
 import { createJsonConfigOperations, readJsonConfig, } from "../read-write-json-config.js";
-/**
- * Get the platform-specific config directory for Copilot CLI.
- *
- * Copilot CLI uses an unconventional XDG pattern: `$XDG_CONFIG_HOME/.copilot`
- * (with the dot prefix inside XDG_CONFIG_HOME, unlike typical XDG conventions
- * which would use `$XDG_CONFIG_HOME/copilot` without the dot).
- *
- * Verified against decompiled Copilot CLI source (sdk/index.js:67574):
- * ```js
- * path.join(process.env.XDG_CONFIG_HOME, ".copilot")
- * ```
- *
- * Falls back to ~/.copilot when XDG_CONFIG_HOME is not set.
- */
-function getPlatformConfigDirectory() {
-    const xdgConfig = process.env.XDG_CONFIG_HOME;
-    if (xdgConfig) {
-        return path.join(xdgConfig, ".copilot");
-    }
-    return path.join(homedir(), ".copilot");
-}
 /**
  * Get the config.json path for a config directory.
  */
@@ -103,11 +82,15 @@ function writeModel(configDirectory, model) {
         };
     }
 }
+// Get path info from axshared (single source of truth)
+const pathInfo = getAgentPathInfo("copilot");
 /** Copilot CLI ConfigReader */
 const copilotConfigReader = {
     agentId: "copilot",
-    defaultConfigDir: getPlatformConfigDirectory,
-    envVar: "GITHUB_COPILOT_CONFIG_DIR",
+    defaultConfigDir: pathInfo.defaultConfigDir,
+    envVar: pathInfo.envVar,
+    subdirectory: pathInfo.subdirectory,
+    buildRuntimeEnvironment: pathInfo.buildRuntimeEnvironment,
     readPermissions,
     readModel,
     writeModel,

package/dist/agents/copilot.js

@@ -43,7 +43,7 @@ function build(config, output) {
                 reason: "Copilot CLI uses runtime approval prompts, not pre-configured allow lists",
                 suggestions: [
                     "Copilot CLI will prompt for approval when tools are used",
-                    "Use a different agent for pre-configured permissions (e.g., claude-code)",
+                    "Use a different agent for pre-configured permissions (e.g., claude)",
                 ],
             });
         }
@@ -53,7 +53,7 @@ function build(config, output) {
                 rule,
                 reason: "Copilot CLI does not support denying tools via configuration",
                 suggestions: [
-                    "Use a different agent that supports deny rules (e.g., claude-code)",
+                    "Use a different agent that supports deny rules (e.g., claude)",
                     "Remove the deny rule",
                 ],
             });

package/dist/agents/gemini-reader.js

@@ -4,9 +4,9 @@
  * Reads and writes Gemini CLI configuration from settings.json and policy TOML files.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import path from "node:path";
 import TOML from "@iarna/toml";
+import { getAgentPathInfo } from "axshared";
 import { atomicWriteFileSync } from "../atomic-write.js";
 import { registerConfigReader } from "../reader.js";
 import { createJsonConfigOperations, readJsonConfig, } from "../read-write-json-config.js";
@@ -141,11 +141,15 @@ function writeModel(configDirectory, model) {
         return { ok: false, error: `Failed to write Gemini CLI model: ${message}` };
     }
 }
+// Get path info from axshared (single source of truth)
+const pathInfo = getAgentPathInfo("gemini");
 /** Gemini CLI ConfigReader */
 const geminiConfigReader = {
     agentId: "gemini",
-    defaultConfigDir: () => path.join(homedir(), ".gemini"),
-    envVar: "GEMINI_DIR",
+    defaultConfigDir: pathInfo.defaultConfigDir,
+    envVar: pathInfo.envVar,
+    subdirectory: pathInfo.subdirectory,
+    buildRuntimeEnvironment: pathInfo.buildRuntimeEnvironment,
     readPermissions,
     readModel,
     writeModel,

package/dist/agents/gemini.js

@@ -106,7 +106,7 @@ function build(config, output) {
                     reason: "Gemini CLI 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)",
+                        "Use a different agent that supports path restrictions (e.g., claude)",
                     ],
                 });
             }

package/dist/agents/opencode-reader.js

@@ -4,8 +4,8 @@
  * Reads and writes OpenCode configuration from opencode.json.
  */
 import { mkdirSync } from "node:fs";
-import { homedir } from "node:os";
 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";
@@ -118,11 +118,15 @@ function writeModel(configDirectory, model) {
         return { ok: false, error: `Failed to write OpenCode model: ${message}` };
     }
 }
+// Get path info from axshared (single source of truth)
+const pathInfo = getAgentPathInfo("opencode");
 /** OpenCode ConfigReader */
 const openCodeConfigReader = {
     agentId: "opencode",
-    defaultConfigDir: () => path.join(homedir(), ".opencode"),
-    envVar: "OPENCODE_CONFIG_DIR",
+    defaultConfigDir: pathInfo.defaultConfigDir,
+    envVar: pathInfo.envVar,
+    subdirectory: pathInfo.subdirectory,
+    buildRuntimeEnvironment: pathInfo.buildRuntimeEnvironment,
     readPermissions,
     readModel,
     writeModel,

package/dist/agents/opencode.js

@@ -10,6 +10,7 @@
  */
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { getAgentConfigSubdirectory } from "axshared";
 import { atomicWriteFileSync } from "../atomic-write.js";
 import { registerConfigBuilder } from "../builder.js";
 // Re-export reader
@@ -51,7 +52,7 @@ function build(config, output) {
                     reason: "OpenCode 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)",
+                        "Use a different agent that supports path restrictions (e.g., claude)",
                     ],
                 });
             }
@@ -61,7 +62,11 @@ function build(config, output) {
     if (errors.length > 0) {
         return { ok: false, errors };
     }
-    const configPath = path.join(output, "opencode.json");
+    // OpenCode expects config at XDG_CONFIG_HOME/opencode/opencode.json
+    const subdirectory = getAgentConfigSubdirectory("opencode") ?? "opencode";
+    const openCodeDirectory = path.join(output, subdirectory);
+    mkdirSync(openCodeDirectory, { recursive: true });
+    const configPath = path.join(openCodeDirectory, "opencode.json");
     // Build permission config
     const permissionConfig = {};
     if (permissions) {
@@ -153,7 +158,10 @@ function build(config, output) {
     atomicWriteFileSync(configPath, JSON.stringify(openCodeConfig, undefined, 2));
     return {
         ok: true,
-        env: { OPENCODE_CONFIG_DIR: output },
+        env: {
+            XDG_CONFIG_HOME: output,
+            XDG_DATA_HOME: output,
+        },
         warnings,
     };
 }

package/dist/cli.d.ts

@@ -4,7 +4,7 @@
  *
  * Manages configurations for AI coding agents.
  */
-import "./agents/claude-code.js";
+import "./agents/claude.js";
 import "./agents/codex.js";
 import "./agents/copilot.js";
 import "./agents/gemini.js";

package/dist/cli.js

@@ -13,7 +13,7 @@ import { handleGetRaw } from "./commands/get-raw.js";
 import { handleSet } from "./commands/set.js";
 import { handleSetRaw } from "./commands/set-raw.js";
 // Import to trigger self-registration
-import "./agents/claude-code.js";
+import "./agents/claude.js";
 import "./agents/codex.js";
 import "./agents/copilot.js";
 import "./agents/gemini.js";
@@ -33,29 +33,29 @@ const program = new Command()
     .addHelpText("after", String.raw `
 Examples:
   # Create config and source it in current shell
-  eval $(axconfig create --agent claude-code --output /tmp/cfg --allow read)
+  eval $(axconfig create --agent claude --output /tmp/cfg --allow read)
 
   # Get current settings
-  axconfig get --agent claude-code allow
-  axconfig get --agent claude-code deny
-  axconfig get --agent claude-code model
+  axconfig get --agent claude allow
+  axconfig get --agent claude deny
+  axconfig get --agent claude model
 
   # 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"
+  axconfig set --agent claude allow "read,glob"
+  axconfig set --agent claude deny "bash:rm *"
+  axconfig set --agent claude model "claude-sonnet-4-20250514"
 
   # Replace instead of merge
-  axconfig set --agent claude-code allow "read,glob" --replace
+  axconfig set --agent claude allow "read,glob" --replace
 
   # Get raw config value
-  axconfig get-raw --agent claude-code permissions.allow
+  axconfig get-raw --agent claude permissions.allow
 
   # Extract allow rules as JSON and filter with jq
-  axconfig get --agent claude-code allow --format json | jq '.'
+  axconfig get --agent claude allow --format json | jq '.'
 
   # Capture in shell variable
-  MODEL=$(axconfig get --agent claude-code model)`);
+  MODEL=$(axconfig get --agent claude model)`);
 program
     .command("create")
     .description("Create agent-specific configuration")

package/dist/get-agent-runtime-environment.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Agent runtime environment utilities.
+ *
+ * Provides functions to compute environment variables for running agents
+ * with custom config directories. Delegates to axshared for path info.
+ */
+import type { AgentCli } from "axshared";
+/** Result type for getAgentConfigEnvironment */
+type GetAgentConfigEnvironmentResult = {
+    ok: true;
+    env: Record<string, string>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Get agent-specific environment variables for a custom config directory.
+ *
+ * Computes the environment variables needed to run an agent with a specific
+ * config directory. This handles agents that require the env var to point to
+ * a parent directory (e.g., HOME for gemini, XDG_DATA_HOME for opencode).
+ *
+ * @param agent - The agent CLI identifier
+ * @param configDirectory - The config directory path (must end with expected suffix for some agents)
+ * @returns Result with agent-specific env vars, or error if configDirectory is invalid
+ *
+ * @example
+ * // Claude: env var points directly to config dir
+ * getAgentConfigEnvironment("claude", "/tmp/test/.claude")
+ * // Returns: { ok: true, env: { CLAUDE_CONFIG_DIR: "/tmp/test/.claude" } }
+ *
+ * // Gemini: env var points to parent (HOME), config is in .gemini subdirectory
+ * getAgentConfigEnvironment("gemini", "/tmp/test/.gemini")
+ * // Returns: { ok: true, env: { HOME: "/tmp/test", GEMINI_FORCE_FILE_STORAGE: "true" } }
+ */
+declare function getAgentConfigEnvironment(agent: AgentCli, configDirectory: string): GetAgentConfigEnvironmentResult;
+export { getAgentConfigEnvironment, type GetAgentConfigEnvironmentResult };

package/dist/get-agent-runtime-environment.js

@@ -0,0 +1,48 @@
+/**
+ * Agent runtime environment utilities.
+ *
+ * Provides functions to compute environment variables for running agents
+ * with custom config directories. Delegates to axshared for path info.
+ */
+import path from "node:path";
+import { buildAgentRuntimeEnvironment, getAgentConfigSubdirectory, } from "axshared";
+/**
+ * Get agent-specific environment variables for a custom config directory.
+ *
+ * Computes the environment variables needed to run an agent with a specific
+ * config directory. This handles agents that require the env var to point to
+ * a parent directory (e.g., HOME for gemini, XDG_DATA_HOME for opencode).
+ *
+ * @param agent - The agent CLI identifier
+ * @param configDirectory - The config directory path (must end with expected suffix for some agents)
+ * @returns Result with agent-specific env vars, or error if configDirectory is invalid
+ *
+ * @example
+ * // Claude: env var points directly to config dir
+ * getAgentConfigEnvironment("claude", "/tmp/test/.claude")
+ * // Returns: { ok: true, env: { CLAUDE_CONFIG_DIR: "/tmp/test/.claude" } }
+ *
+ * // Gemini: env var points to parent (HOME), config is in .gemini subdirectory
+ * getAgentConfigEnvironment("gemini", "/tmp/test/.gemini")
+ * // Returns: { ok: true, env: { HOME: "/tmp/test", GEMINI_FORCE_FILE_STORAGE: "true" } }
+ */
+function getAgentConfigEnvironment(agent, configDirectory) {
+    const subdirectory = getAgentConfigSubdirectory(agent);
+    const resolvedConfigDirectory = path.resolve(configDirectory);
+    // Validate subdirectory suffix for agents that require it
+    if (subdirectory !== undefined) {
+        const actualSuffix = path.basename(resolvedConfigDirectory);
+        if (actualSuffix !== subdirectory) {
+            return {
+                ok: false,
+                error: `Config directory for ${agent} must end with '${subdirectory}', got '${actualSuffix}'.\n` +
+                    `Expected path like: /some/path/${subdirectory}`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        env: buildAgentRuntimeEnvironment(agent, resolvedConfigDirectory),
+    };
+}
+export { getAgentConfigEnvironment };

package/dist/index.d.ts

@@ -21,13 +21,14 @@ export { formatRule, parsePermissions, parseRule, parseRuleList, } from "./parse
 export { getConfigBuilder, registerConfigBuilder } from "./builder.js";
 export { getConfigReader, registerConfigReader } from "./reader.js";
 export { resolveConfigPath } from "./resolve-config-path.js";
+export { getAgentConfigEnvironment, type GetAgentConfigEnvironmentResult, } from "./get-agent-runtime-environment.js";
 export { buildAgentConfig, formatPermissionErrors, formatPermissionWarnings, } from "./build-agent-config.js";
-import "./agents/claude-code.js";
+import "./agents/claude.js";
 import "./agents/codex.js";
 import "./agents/copilot.js";
 import "./agents/gemini.js";
 import "./agents/opencode.js";
-export { claudeCodeConfigBuilder, claudeCodeConfigReader, } from "./agents/claude-code.js";
+export { claudeCodeConfigBuilder, claudeCodeConfigReader, } from "./agents/claude.js";
 export { codexConfigBuilder, codexConfigReader } from "./agents/codex.js";
 export { copilotConfigBuilder, copilotConfigReader } from "./agents/copilot.js";
 export { geminiConfigBuilder, geminiConfigReader } from "./agents/gemini.js";

package/dist/index.js

@@ -24,16 +24,18 @@ export { getConfigBuilder, registerConfigBuilder } from "./builder.js";
 export { getConfigReader, registerConfigReader } from "./reader.js";
 // Path resolution
 export { resolveConfigPath } from "./resolve-config-path.js";
+// Runtime environment
+export { getAgentConfigEnvironment, } from "./get-agent-runtime-environment.js";
 // High-level API
 export { buildAgentConfig, formatPermissionErrors, formatPermissionWarnings, } from "./build-agent-config.js";
 // Import agent modules to trigger self-registration
-import "./agents/claude-code.js";
+import "./agents/claude.js";
 import "./agents/codex.js";
 import "./agents/copilot.js";
 import "./agents/gemini.js";
 import "./agents/opencode.js";
 // Export agent builders for direct access
-export { claudeCodeConfigBuilder, claudeCodeConfigReader, } from "./agents/claude-code.js";
+export { claudeCodeConfigBuilder, claudeCodeConfigReader, } from "./agents/claude.js";
 export { codexConfigBuilder, codexConfigReader } from "./agents/codex.js";
 export { copilotConfigBuilder, copilotConfigReader } from "./agents/copilot.js";
 export { geminiConfigBuilder, geminiConfigReader } from "./agents/gemini.js";

package/dist/resolve-config-path.d.ts

@@ -10,10 +10,12 @@ import type { AgentCli } from "axshared";
  * 2. Agent's environment variable
  * 3. Agent's default config directory
  *
+ * Delegates to axshared's resolveAgentConfigDirectory, which is the canonical
+ * source of truth for agent path resolution.
+ *
  * @param agentId - The agent to resolve config for
  * @param providedPath - Optional path from --path option
  * @returns The resolved config directory path
- * @throws Error if no reader is registered for the agent
  */
 declare function resolveConfigPath(agentId: AgentCli, providedPath?: string): string;
 export { resolveConfigPath };

package/dist/resolve-config-path.js

@@ -1,7 +1,7 @@
 /**
  * Resolve agent config directory from --path option, env vars, or defaults.
  */
-import { getConfigReader } from "./reader.js";
+import { resolveAgentConfigDirectory } from "axshared";
 /**
  * Resolve the config directory for an agent.
  *
@@ -10,23 +10,14 @@ import { getConfigReader } from "./reader.js";
  * 2. Agent's environment variable
  * 3. Agent's default config directory
  *
+ * Delegates to axshared's resolveAgentConfigDirectory, which is the canonical
+ * source of truth for agent path resolution.
+ *
  * @param agentId - The agent to resolve config for
  * @param providedPath - Optional path from --path option
  * @returns The resolved config directory path
- * @throws Error if no reader is registered for the agent
  */
 function resolveConfigPath(agentId, providedPath) {
-    if (providedPath) {
-        return providedPath;
-    }
-    const reader = getConfigReader(agentId);
-    if (!reader) {
-        throw new Error(`No config reader registered for agent "${agentId}"`);
-    }
-    const environmentValue = process.env[reader.envVar];
-    if (environmentValue) {
-        return environmentValue;
-    }
-    return reader.defaultConfigDir();
+    return resolveAgentConfigDirectory(agentId, providedPath);
 }
 export { resolveConfigPath };

package/dist/types.d.ts

@@ -133,6 +133,18 @@ interface ConfigReader {
     defaultConfigDir: () => string;
     /** Environment variable that overrides the config directory */
     envVar: string;
+    /**
+     * Subdirectory name within the base path for agents where the env var
+     * points to a parent directory (e.g., ".gemini" for HOME, "opencode" for XDG_DATA_HOME).
+     * Undefined if env var points directly to the config directory.
+     */
+    subdirectory: string | undefined;
+    /**
+     * Build environment variables for running this agent with a custom config directory.
+     * @param basePath - The base path (parent of subdirectory, or config dir if no subdirectory)
+     * @returns Environment variables to set for the agent
+     */
+    buildRuntimeEnvironment: (basePath: string) => Record<string, string>;
     /** Read permissions from agent config and translate to unified format */
     readPermissions: (configDirectory: string) => ReadPermissionsResult;
     /** Read model from agent config */

package/package.json

@@ -2,7 +2,7 @@
   "name": "axconfig",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Unified configuration management for AI coding agents - common API for permissions, settings, and config across Claude Code, Codex, Gemini CLI, and OpenCode",
   "repository": {
     "type": "git",
@@ -68,7 +68,7 @@
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
     "@iarna/toml": "^2.2.5",
-    "axshared": "^1.1.0",
+    "axshared": "^1.2.0",
     "commander": "^14.0.2"
   },
   "devDependencies": {