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

• 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

{session_id, resume}

{tool, input, ...}

{tool, result, ...}

{session_id, ...}

{agent, ...}

{message, ...}

{tool, ...}

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

.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

devenv.nix

options.alto

devenv.nix

scripts.*

devenv.nix

tasks."alto:deploy"

devenv.nix

claude.code.agents

devenv.nix

claude.code.hooks

agents/*.md

hooks/*.py

skills/*/SKILL.md

templates/CLAUDE.md.setup

templates/CLAUDE.md.build

templates/CLAUDE.md.dev

templates/default/

nix flake init

ARCHITECTURE.md

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

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

echo "$(jq ...)"

devenv shell

--refresh

Nix String Escaping (

''

strings)

• ''$

  ->

  $

  (escape dollar)

• '''

  ->

  ''

  (escape quotes)

• \n

  -> literal

  \n

  (not newline)
• Use actual newlines for line breaks