Achhina's Digital Garden

2026-09-19 Unified Coding Agents Interface and AGY Skills MCP

3 min read

2026-09-19 Unified Coding Agents Interface and AGY Skills MCP

What I set out to do

Diagnose why agy (Antigravity CLI) showed no configured MCP servers and was missing Obsidian knowledge skills (knowledge-management, note, people), rename the legacy gemini.nix module to agy.nix, and implement a unified coding agent interface across all coding agents.

What I actually did

  • Diagnosed root causes:

    1. programs.antigravity-cli.enableMcpIntegration defaulted to false upstream and was omitted from gemini.nix. Home Manager had left ~/.gemini/config/mcp_config.json unmanaged as a stale, empty 0-byte file from July 26.
    2. knowledge-management, note, and people were declared in common/lib.nix as Claude-only skills and only wired into claude.nix.

  • Renamed module:

    • Moved nix/home-manager/modules/coding-agents/gemini to nix/home-manager/modules/coding-agents/agy.
    • Renamed gemini.nix to agy.nix and updated error contexts, comments, and AGENTS.md.

  • Built unified coding agents interface:

    • Created coordinator module nix/home-manager/modules/coding-agents/common/coding-agents.nix declaring programs.codingAgents = { enable, enableMcp, skills, contextFile }.
    • Moved gen-people-schema.py and people-schema-prose.md into coding-agents/common/ and consolidated peopleSchemaGenerated generation.
    • Included knowledge-management, note, and people in the universal skills set alongside portableSkills.
    • Propagated skills and enableMcpIntegration to programs.antigravity-cli, programs.pi-coding-agent, programs.codex, and programs.claude-code.
    • Wired note-template.md and people-schema.md dynamic asset links to .claude/, .gemini/config/, and .pi/agent/ skill directories.

  • Added contract test:

    • Created nix/tests/coding-agents-contract.nix and registered it in nix/tests/default.nix.
    • Verifies that all enabled coding agents mount all universal skills and enable MCP integration.

  • Verified and deployed:

    • Ran just check (passed formatting, linting, deadnix, statix, and flake checks).
    • Executed hm switch, removing the stale 0-byte ~/.gemini/config/mcp_config.json so Home Manager deployed the live MCP configuration and the complete skill set into ~/.gemini/config/skills/.

  • Unified global context (instructions):

    • Wired programs.codingAgents.contextFile (common/context/AGENTS.md) directly to programs.antigravity-cli.context.GEMINI, programs.pi-coding-agent.context, programs.codex.context, and home.mutableFile for .claude/CLAUDE.md and .codex/AGENTS.md.
    • Linked programs.claudeSkillSync.instructions.source so account-wide instructions track codingAgents.contextFile.
    • Stripped hardcoded context paths from agy.nix, claude.nix, pi.nix, codex.nix, and skill-sync.nix.
    • Added context validation to nix/tests/coding-agents-contract.nix and verified with just check and hm switch.

  • Unified Universal Agents and Permissions:

    • Extended programs.codingAgents with agents (attrsOf (either path package)) defaulting to dynamic discovery of ./agents/*.md (comment-remover, commit, github-automation, python-reviewer, template-filler).
    • Added centralized permissions options (allow, ask, deny) with baseline guardrails (ask for git push, git checkout; deny for git -C, git --git-dir, git --work-tree).
    • Projected agents across all four targets:
      • Claude Code: programs.claude-code.agents = cfg.agents; (symlinked into ~/.claude/agents/).
      • Pi: programs.pi-coding-agent.agents = cfg.agents; and prompts = cfg.agents; (symlinked into ~/.pi/agent/agents/ and ~/.pi/agent/prompts/).
      • Antigravity: programs.antigravity-cli.commands = cfg.agents; mapped via formatForGeminiCommand, then re-injected as skills at ~/.gemini/config/skills/.
      • Codex: dynamically compiled into standalone Codex skills with SKILL.md via formatForCodexSkill, deployed into ~/.codex/skills/.
    • Projected permissions across all four targets:
      • Antigravity CLI: translated to command(...) syntax in programs.antigravity-cli.permissions.
      • Pi: injected into ~/.pi/agent/extensions/pi-automode/config.json under permissions with bash(...) patterns.
      • Claude Code: translated into Bash(...) patterns and merged into baseAskPermissions and baseDenyPermissions.
      • Codex: converted into Starlark prefix_rule(...) patterns with prompt and forbidden decisions in rules.default.
    • Expanded nix/tests/coding-agents-contract.nix with assertions for all universal agents and baseline permissions on every enabled agent.
    • Verified with just check, nix flake check, and activated via hm switch.

What was striking

  • Antigravity’s upstream Home Manager module (programs.antigravity-cli) already contained full support for transforming programs.mcp.servers into ~/.gemini/config/mcp_config.json with stdio and http/serverUrl handling. It was simply disabled because enableMcpIntegration was unset.
  • Inverting control through a coordinator module in common/ eliminated boilerplate across four separate agent modules without requiring custom submodule wrappers over upstream Home Manager options.
  • Global context files across agents differ in deployment requirements (some like Claude and Codex require mutable real files to allow runtime memory updates, while Antigravity and Pi take store symlinks), but the source of truth can be completely centralized through codingAgents.contextFile.

Graph View

Backlinks