{"_id":"@background-agents/agent-configuration","name":"@background-agents/agent-configuration","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@background-agents/agent-configuration","version":"0.1.0","description":"Translation layer between coding agents' configuration formats","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./permissions":{"import":{"types":"./dist/permissions/index.d.ts","default":"./dist/permissions/index.js"},"require":{"types":"./dist/permissions/index.d.cts","default":"./dist/permissions/index.cjs"}},"./mcp":{"import":{"types":"./dist/mcp/index.d.ts","default":"./dist/mcp/index.js"},"require":{"types":"./dist/mcp/index.d.cts","default":"./dist/mcp/index.cjs"}},"./package.json":"./package.json"},"scripts":{"build":"tsup src/index.ts src/permissions/index.ts src/mcp/index.ts --format esm,cjs --dts --clean --sourcemap","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepare":"npm run build"},"keywords":["agent","configuration","mcp","permissions","translation"],"license":"MIT","devDependencies":{"@types/node":"^20.10.0","tsup":"^8.0.0","typescript":"^5.3.0"},"peerDependencies":{"@daytonaio/sdk":"^0.170.0"},"peerDependenciesMeta":{"@daytonaio/sdk":{"optional":true}},"publishConfig":{"access":"public"},"_id":"@background-agents/agent-configuration@0.1.0","gitHead":"803bd192a97990ac03f5d559b923f7633a853c96","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Rc5D4C2xbJstfQyLij/6K+54vk6APuFyT3VqY/Da1NC56IZIHMttJohIHJ346K0WZTod/bKMP2Gh6Zx0ovmyOg==","shasum":"6c3a10f06e9cd62c1627398e2bb2c0de4e9ec56a","tarball":"https://registry.npmjs.org/@background-agents/agent-configuration/-/agent-configuration-0.1.0.tgz","fileCount":24,"unpackedSize":158507,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDBc0VO/Uq+gl8foUysJ87TfrQoxZWIdeDO5cIOZwTyEAIhALKYNGzqGq8rXSe2HTwJzQuiCsOnS4hjtYaoMkxp+ZvI"}]},"_npmUser":{"name":"jamesmurdza","email":"jamesmurdza@gmail.com"},"directories":{},"maintainers":[{"name":"jamesmurdza","email":"jamesmurdza@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-configuration_0.1.0_1782598704774_0.006305752739866888"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-27T22:18:24.602Z","0.1.0":"2026-06-27T22:18:24.919Z","modified":"2026-06-27T22:18:25.151Z"},"maintainers":[{"name":"jamesmurdza","email":"jamesmurdza@gmail.com"}],"description":"Translation layer between coding agents' configuration formats","keywords":["agent","configuration","mcp","permissions","translation"],"license":"MIT","readme":"# @background-agents/agent-configuration\n\nA translation layer between coding agents' configuration formats.\n\n## Overview\n\nEvery coding agent (Claude Code, Codex, Gemini, OpenCode, Goose, Copilot, Kilo,\nKimi) loads MCP servers and command-permission rules from a different file, in a\ndifferent schema, with a different transport convention. This package takes\n**agent-agnostic inputs** and renders the correct **native config** for whichever\nagent is running, then installs it into the sandbox.\n\nThere are two translation domains:\n\n1. **MCP servers** — given a list of `{ name, url, bearerToken }` connections,\n   write the right config file in the right format for the target agent.\n2. **Command permissions** — given a `CommandPolicy` (a list of command rules to\n   deny), render it into the agent's native mechanism: a Claude `PreToolUse` bash\n   hook, Codex Starlark `prefix_rule`s, or the OpenCode `OPENCODE_PERMISSION` JSON.\n\nYou supply the inputs; the package handles the per-agent formats. The command\nruleset itself (e.g. \"block `git push`/`rebase`/...\") stays in your app — in this\nrepo it lives in `packages/web/lib/git-policy.ts` as `DEFAULT_GIT_POLICY` — so the\nsame policy renders identically across every agent and lives in one place to\nedit.\n\n## Installation\n\n```bash\nnpm install @background-agents/agent-configuration\n```\n\n## Command permissions\n\nDescribe what to deny with the agent-agnostic `CommandPolicy` vocabulary, then\nhand it to the renderer for whichever agent is running:\n\n```ts\nimport {\n  setupClaudePermissions,\n  setupCodexPermissions,\n  renderOpenCodePermissionEnv,\n  type CommandPolicy,\n} from \"@background-agents/agent-configuration/permissions\"\n\nconst policy: CommandPolicy = {\n  deny: [\n    { kind: \"deny\", prefix: [\"git\", \"push\"], reason: \"Pushing is automatic.\" },\n    {\n      kind: \"deny-except\",\n      prefix: [\"git\", \"rebase\"],\n      allow: [\"--continue\", \"--abort\", \"--skip\"],\n      reason: \"rebase rewrites history.\",\n    },\n    // ...\n  ],\n}\n\nawait setupClaudePermissions(sandbox, policy) // Claude Code bash hook\nawait setupCodexPermissions(sandbox, policy)  // Codex Starlark rules\nenv.OPENCODE_PERMISSION = renderOpenCodePermissionEnv(policy) // OpenCode env\n```\n\n### Rule kinds\n\n| `kind`            | Matches                                                       | Example                                           |\n| ----------------- | ------------------------------------------------------------ | ------------------------------------------------- |\n| `deny`            | the prefix, always                                           | `[\"git\", \"push\"]`                                 |\n| `deny-with-flag`  | the prefix when any `flags` token appears in the args        | `[\"git\", \"branch\"]` + `[\"-d\", \"-D\"]`              |\n| `deny-except`     | the prefix unless the next token is in `allow`               | `[\"git\", \"rebase\"]` + `[\"--continue\", \"--abort\"]` |\n| `deny-branch-arg` | the prefix + a branch ref (`allowFileForms` permits `.`/`--`/`HEAD`) | `[\"git\", \"checkout\"]`                      |\n\nEach renderer expresses these as faithfully as its format allows. Where a format\ncan't model a nuance — OpenCode globs can't say \"deny unless `--continue`\", and\nCodex `prefix_rule`s can't match a flag mid-argument — the renderer falls back\nto denying the whole prefix (so e.g. `git checkout`/`switch` are blocked\nentirely for Codex/OpenCode, and agents are told to use `git restore`).\n\nRenderers are also exposed as pure functions (`renderClaudeHook`,\n`renderCodexRules`, `renderOpenCodePermissions`) for testing or custom install\nflows. OpenCode additionally merges in `OPENCODE_BASELINE_PERMISSIONS` — the\nbaseline allows (`edit`, `webfetch`, `external_directory`) the agent needs to\nrun headlessly.\n\n## MCP setup\n\nWrites per-agent MCP server configs into the sandbox before the agent CLI\nstarts. Supported agents: `claude-code`, `codex`, `gemini`, `opencode`, `goose`,\n`copilot`, `kilo`, `kimi`. It's a no-op for agents that don't support MCP.\n\n```ts\nimport { setupMcpForAgent } from \"@background-agents/agent-configuration/mcp\"\n\nawait setupMcpForAgent(sandbox, {\n  agent: \"claude-code\",\n  servers: [\n    {\n      name: \"github\",\n      url: \"https://api.githubcopilot.com/mcp/\",\n      bearerToken: \"<github-installation-token>\",\n    },\n  ],\n})\n```\n\nEach agent CLI loads MCP servers from a different config file with a different\nschema; this helper writes the correct file in the correct format. Passing an\nempty `servers` list still writes the config, clearing any stale entries from a\nprevious run in a reused sandbox.\n\n## Exports\n\n```ts\n// \"@background-agents/agent-configuration/permissions\"\nimport {\n  type CommandPolicy,\n  type CommandRule,\n  // Claude\n  setupClaudePermissions,\n  renderClaudeHook,\n  CLAUDE_HOOK_FILE,\n  CLAUDE_SETTINGS_FILE,\n  CLAUDE_SETTINGS,\n  // Codex\n  setupCodexPermissions,\n  renderCodexRules,\n  CODEX_RULES_FILE,\n  // OpenCode\n  renderOpenCodePermissions,\n  renderOpenCodePermissionEnv,\n  OPENCODE_BASELINE_PERMISSIONS,\n} from \"@background-agents/agent-configuration/permissions\"\n\n// \"@background-agents/agent-configuration/mcp\"\nimport {\n  setupMcpForAgent,\n  type AgentMcpServer,\n  type SetupMcpOptions,\n} from \"@background-agents/agent-configuration/mcp\"\n```\n\nThe package root (`.`) re-exports both submodules.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a256efb4ecfce3367c2a66aba881beda"}