ALTO Development Guide

Reference for developing ALTO. Use URLs for authoritative docs, summaries for quick reference.

Devenv MCP (always available)

ALTO configures the devenv MCP server automatically. Use it for:

• Package search - Find packages and their configuration options
• Config understanding - Understand devenv syntax and patterns
• Config generation - Generate valid devenv configurations

The MCP is available as devenv server. Use MCP tools to query it when you need:

• What packages are available for a language/tool
• How to configure a specific service
• Valid options for a devenv setting

Documentation Sources

Devenv (authoritative)

Claude Code (authoritative)

Community resources

Devenv Quick Reference

Scripts

scripts.<name> = {
  exec = ''
    echo "script body"
  '';
  description = "Shown in devenv info";
};

• Available as commands in shell
• Use ${variable} for nix interpolation
• Use ''$ to escape $ in bash

Tasks

tasks."namespace:name" = {
  exec = ''
    echo "task body"
  '';
  before = [ "devenv:enterShell" ];  # Run before shell entry
  # after = [ "other:task" ];        # Run after another task
};

• Run automatically on shell entry (if before includes enterShell)
• Good for setup/deployment that should happen every time

Native Imports (not flakes)

# devenv.yaml
inputs:
  alto:
    url: github:gonzaloetjo/alto
    flake: false  # Critical: native import mode

imports:
  - alto  # References the input name

• flake: false = use devenv's native import system
• ALTO activates on import, configure with alto.orchestrator

Claude Code Quick Reference

Hook Types

Hook Configuration (devenv)

claude.code.hooks.<name> = {
  hookType = "PostToolUse";  # Required
  matcher = "Bash";          # Tool name, or "*" for all
  command = "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/script.py";
};

Hook Script Pattern

#!/usr/bin/env python3
import json, sys, os
from pathlib import Path

def main():
    hook_data = json.load(sys.stdin)
    project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", "."))

    # Do work...

    # For SessionStart: print context for Claude to see
    print("Context message")

if __name__ == "__main__":
    main()

Agents (devenv)

claude.code.agents.<name> = {
  description = "Shown when listing agents";
  tools = [ "Read" "Edit" "Bash" "Grep" "Glob" "WebFetch" ];
  model = "opus";  # or "sonnet", "haiku"
  prompt = ''
    Agent system prompt here.
    This defines behavior, not user request.
  '';
};

Available Tools

Read, Write, Edit, Bash, Grep, Glob, LS, WebFetch, WebSearch, Task, TodoWrite, AskUserQuestion

Skills

Place SKILL.md in .claude/skills/<name>/

• Invoked with /<skill-name> or automatically by context
• Content is instructions for Claude

MCP Servers

claude.code.mcpServers.<name> = {
  type = "stdio";  # or "http"
  command = "devenv";
  args = [ "mcp" ];
  env = { DEVENV_ROOT = "."; };
};

Permissions

claude.code.permissions = {
  Bash = {
    allow = [ "git:*" "npm:*" ];
    deny = [ "rm -rf:*" "sudo:*" ];
  };
  Read = {
    deny = [ ".env" "secrets/**" ];
  };
};

ALTO File Reference

Testing Workflows

Fresh install

mkdir /tmp/test && cd /tmp/test
nix --extra-experimental-features 'nix-command flakes' flake init -t github:gonzaloetjo/alto --refresh
devenv shell
# Check: ls .claude/ runs/ CLAUDE.md

Local development

# test project's devenv.yaml - use local path
imports:
  - /absolute/path/to/alto

Then devenv shell to rebuild with local changes.

Verify deployment

ls -la .claude/agents/     # Symlinks to nix store
ls -la .claude/hooks/      # Python files
cat runs/state.json        # ALTO state
cat .claude/settings.json  # Permissions + hooks

Common Issues

Nix String Escaping ('' strings)

• ''$ -> $ (escape dollar)
• ''' -> '' (escape quotes)
• \n -> literal \n (not newline)
• Use actual newlines for line breaks