Helmsman

Helmsman

Adaptive instruction server for AI coding agents.

The Problem

Static AGENTS.md files create instruction entropy collapse.

The same instructions for Opus, Sonnet, and Haiku is fantasy. They have different capabilities, different costs, and different failure modes. Static instructions:

• Rot silently - written once, never updated, drift from reality
• Waste tokens - Opus doesn't need step-by-step guidance
• Cause failures - Haiku needs guardrails it doesn't get
• Ignore context - "use brew" when you're on Arch with mise

The real cost isn't just tokens - it's instruction determinism. You can't control what you can't adapt.

The Solution

Helmsman serves dynamic, context-aware instructions via MCP (and CLI):

• Model-aware: Opus gets minimal guidance, Haiku gets verbose hand-holding
• Environment-aware: Detects OS, shell, available tools
• Template-based: Jinja2 templates adapt to context

{% if model.tier == "agi" %}Verify packages exist. You know what to do.{% else %}1. Read the file first with Read tool2. Check for existing patterns3. Verify packages exist - do NOT invent them{% endif %}
{% if env.has_mise %}Use mise for runtime management.{% elif env.has_brew %}Use brew for packages.{% endif %}

Install

cargo install helmsman

Build from source

Requires Rust 1.98 or newer. The repository pins Rust 1.98.1 for local and release builds. From the Helmsman repository directory:

cargo build --release --lockedcargo test --locked

Quick Start

Goal gate (FreeChaOS)

Configure Jev with /reflex, then submit /goal <request>. The flow is work → check_goal → Jev verdict → model response. Helmsman owns the lifecycle; the host journals it and supplies Jev verdicts. Read goal://current for status. The turn stays open for a reply. See helmsman-goals(7) for setup, protocol, and limits.

Instructions and skills

1. Create AGENTS.md.j2 in your project root

2. Add to .mcp.json:

{  "mcpServers": {    "helmsman": {      "type": "stdio",      "command": "helmsman"    }  }}

3. Call the prompt:

/helmsman:instructions claude-opus-4-5-20251101

Tiers

Three capability tiers, parallel to Anthropic's model siblings. Could expand to 4-5, but we're not going the OpenAI route of 40 model names (nano, mini, micro, medium, large...).

monkey

Follows instructions. Useful but needs guardrails. Tell it exactly what to do, what NOT to do, and keep it inside the perimeter. Without guidance, it will hallucinate packages and invent APIs.

Examples: Haiku, GPT-5.2 mini, Gemini Flash

engineer

Knows the basics. Competent but lacks judgment. Will delete your 300GB cache to fix a bug. Bug fixed, but now you wait 4 hours for it to rebuild. Needs boundaries, not hand-holding.

Examples: Sonnet, GPT-5.2 medium, Gemini Pro

agi

The architect. Don't explain how to use cargo or how to publish. It knows. Give it constraints and goals, not procedures. Wasting tokens on step-by-step instructions is burning money.

Examples: Opus, GPT-5.2 high/xhigh, DeepSeek R3

Shortcuts: a/architect (agi), e/eng/standard (engineer), m/basic/simple (monkey)

CLI

helmsman                              # MCP server modehelmsman -i                           # print instructions (default tier)helmsman -i m                         # monkey tierhelmsman -i basic                     # monkey tier (neutral alias)helmsman -i a                         # agi tierhelmsman -i architect                 # agi tier (neutral alias)helmsman -i claude-opus-4-5-20251101  # resolves to agi tierhelmsman -i gpt-4o-mini               # resolves to monkey tier
# Override tier mapping for new/unknown modelshelmsman -i unknown-model --tier engineer
# Show diff between tiershelmsman -i a --diff e                # show AGI vs Engineer differences
helmsman -s commit                    # render .skills/commit.j2helmsman -l                           # list available skillshelmsman --validate                   # check skill syntaxhelmsman -t                           # show token count

Template Context

{# Model #}{{ model.id }}        {# "claude-opus-4-5-20251101" #}{{ model.tier }}      {# "agi", "engineer", "monkey" #}
{# Environment #}{{ env.os }}          {# "macos", "arch", "debian", "alpine" #}{{ env.shell }}       {# "zsh", "bash", "fish", "sh" #}{{ env.in_docker }}   {# true/false #}{{ env.in_ssh }}      {# true/false #}
{# Tools #}{{ env.has_mise }}{{ env.has_brew }}{{ env.has_apt }}{{ env.has_gh }}{{ env.has_git }}

Configuration

Create optional helmsman.toml in:

1. Current directory (project-local)
2. ~/.config/helmsman/ (user global)
3. Set $HELMSMAN_CONFIG env var to override

[defaults]tier = "engineer"
[server]templates_dir = "~/my-templates"

Model → tier mappings are pre-configured for Anthropic, OpenAI, Google, and other major models. Unknown models default to engineer tier.

Skills

Project skills live in .skills/ and are discovered automatically. Files prefixed with _ are partials.

Environment Detection

Helmsman detects OS, shell, and available tools automatically. Best effort only, never authoritative.

Known edge cases:

• SSH + Docker may report wrong shell ($SHELL lies)
• Alpine/busybox may lack expected binaries
• Container detection uses heuristics (cgroup parsing)

Use these values for optimization hints, not hard requirements.

Non-Goals

Things Helmsman deliberately doesn't do:

• Prompt engineering framework - not here to optimize your prompts
• Model memory/learning - stateless, no persistence between calls
• Teaching tool - assumes you know what you're doing
• Configuration management - use real tools for that

Helmsman is infrastructure, not a product.

License

BSD-3-Clause

mcp-name: io.github.seuros/helmsman