Alto Dev Guide

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