AI Configuration

Configure AI models, MCP servers, persona prompts, and keep your AI setup portable across machines.

Overview

EZKeel treats AI tools as first-class citizens in the developer workflow. The ai section of workspace.yaml defines which models to use, while the .claude/ directory holds the runtime configuration (settings, MCP servers, persona). Together, they ensure every developer on the team has the same AI setup.

Model Configuration

Define your preferred models in workspace.yaml:

workspace.yaml
            
ai:
  models:
    default: claude-sonnet-4-5    # primary model
    fast: claude-haiku-4-5       # fast model for quick tasks

These values are used by ezkeel ai to determine which tool to launch and which API key to inject:

claude tools use ANTHROPIC_API_KEY
codex tools use OPENAI_API_KEY
local resolves to the local model (e.g. ollama/llama3) and requires no API key

Using AI Tools

The ezkeel ai command is the unified entry point for all AI tools. It handles secret injection, model resolution, and tool launching in a single command.

terminal

# Use Claude with automatic secret injection $ ezkeel ai claude "refactor the payment module" # Use OpenAI Codex $ ezkeel ai codex "generate API tests" # Use the local model (no API key needed) $ ezkeel ai local "explain this function" # Specify a different environment for secrets $ ezkeel ai claude "review staging config" --env staging

Persona Portability

When you run ezkeel init, a .claude/ directory is scaffolded with your project's AI configuration. This includes settings, MCP server definitions, and the persona prompt from workspace.yaml.

To keep this configuration synchronized across machines and team members, EZKeel uses a dedicated Git branch:

terminal

# Push your local .claude/ config to the shared branch $ ezkeel sync push Persona pushed to origin/ezkeel/persona # On another machine, pull the shared config $ ezkeel sync pull Persona pulled from origin/ezkeel/persona

How it works:

Push stashes your current work, creates/updates the ezkeel/persona branch with the .claude/ directory, force-pushes, then restores your previous branch and stash.
Pull fetches the remote branch and checks out just the .claude/ subtree into your working directory.

Why a separate branch? The .claude/ directory often contains machine-specific paths or personal preferences. Keeping it on a dedicated branch avoids polluting your main branch history while still making it shareable.

Persona Prompt

The ai.persona field in workspace.yaml defines the system prompt used by AI assistants in your project:

workspace.yaml
            
ai:
  persona: |
    You are a senior engineer working on my-project.
    Follow the conventions in CLAUDE.md and AGENTS.md.
    Always write tests for new functionality.
    Prefer small, focused commits.

This prompt is injected into the .claude/ configuration during ezkeel init and can be updated by editing workspace.yaml and re-running the scaffolding.

MCP Servers

EZKeel can configure Model Context Protocol (MCP) servers for your AI tools. MCP servers provide AI assistants with structured access to external tools and data sources.

workspace.yaml
            
            
            
          

ai:
  mcp_servers:
    - name: filesystem
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

    - name: github
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]

    - name: postgres
      command: npx
      args: ["-y", "@modelcontextprotocol/server-postgres", "$DATABASE_URL"]
        

Each server entry specifies:

Field	Description
`name`	Unique identifier for the server
`command`	Executable to launch the server
`args`	Arguments to pass to the command

These MCP server definitions are written into the .claude/ configuration when the project is initialized, making them available to Claude Code and other MCP-compatible tools.