Skip to content

Using ScriptHut from a coding agent

If you want a coding agent (Claude Code, Codex, Cursor, Aider, etc.) to drive ScriptHut on your behalf, you don't need a custom plugin. ScriptHut exposes everything through the CLI; the only wiring needed is teaching the agent that the CLI exists.

cd /path/to/your/project
scripthut agent install            # writes into ./.claude
scripthut agent install --user     # or into ~/.claude, for every project

This installs two things Claude Code picks up automatically:

  • A scripthut skill (.claude/skills/scripthut/SKILL.md) — loads on demand when a task involves submitting or monitoring compute (on a cluster or the local backend), checking cluster status, tailing job logs, managing stacks, probing the result cache, or fetching task manifests. It's deliberately thin: its first instruction is to run scripthut agent prompt for the full, live, config-aware briefing, so nothing in it goes stale when you edit scripthut.yaml. Unlike piping the briefing into CLAUDE.md, it costs no context in sessions that never touch compute.
  • A /scripthut:debug [run-id] slash command (.claude/commands/scripthut/debug.md) — walks the failure-diagnosis flow for a failed run: fetch statuses, pull stderr, classify the cause (stack not ready / resource limit / code bug), propose the fix.

Re-running agent install updates the files in place (they carry a generated by marker). Files you wrote by hand at those paths are never overwritten unless you pass --force.

Other agents: pipe in the briefing

For agents without a skill mechanism, give them the output of one command:

scripthut agent prompt

That prints a Markdown briefing — a static reference for the CLI surface, exit codes, and submission patterns, plus a live inventory of the backends, sources, and stacks your local scripthut.yaml defines. Drop the output where your agent reads context and you're done.

1. Project file the agent auto-loads

Most coding agents read a file at the project root on startup. Pipe the briefing there once per project:

cd /path/to/your/project
scripthut agent prompt > AGENTS.md      # Codex reads AGENTS.md
scripthut agent prompt > .cursorrules   # Cursor reads .cursorrules

(Careful: > replaces the file. If you already keep instructions in AGENTS.md, append with >> or reference a separate file instead.)

Re-run after you change scripthut.yaml (new backend, new source, new stack) so the inventory section stays accurate.

2. Inject into a Claude Code session

Claude Code's ! prefix runs a shell command and pipes its output directly into the conversation. Type this as a message in the chat:

!scripthut agent prompt

Useful when you want to brief an existing session without persisting to a file.

3. Copy-paste

Same idea, manual:

scripthut agent prompt | pbcopy        # macOS
scripthut agent prompt | xclip -selection clipboard  # Linux

…then ⌘V into the agent's prompt area.

What the briefing covers

A re-read shows you the current contents, but for orientation:

  • Inventory — the backends, stacks, and sources you've configured (when a scripthut.yaml is discoverable).
  • Submitting work — the three input modes for scripthut task run (--inline-script, positional command, --from-stdin) and when to prefer a source workflow (scripthut workflow run).
  • TaskDefinition shape — the JSON schema agents need when constructing tasks programmatically.
  • Resource sizing defaults — start small (1 CPU / 1 GB / 5 min), escalate only when an earlier run hit OOM or timed out.
  • Editing scripthut.yaml — the two-layer model (user-global vs. project-local), what each file is allowed to carry, merge semantics, env-rule schema (set / if / include / stacks / append / init), and edit discipline (read first, minimal diff, hot-reload not restart).
  • Stacks — full define → install → reference flow, including the v0.7.1 stacks: [name] env-rule reference syntax and the two failure modes that matter (unknown name → loud ValueError, no auto-install at submit time).
  • Verify-then-submit loop — the read-only steps the agent should run before any submission (status, backend list, source view, stack check, --dry-run) and how to track a run's status / output / logs after.
  • Gotchas and exit codes — working_dir is a path on the backend, partition names are remapped per backend, exit code 2 is reserved for run watch --exit-status failure, etc.

Targeting a remote server

scripthut agent prompt itself reads your local scripthut.yaml to populate the inventory section — it doesn't pull from a running server. When the agent is working against a remote server (SCRIPTHUT_SERVER=...), tell it to also run these against the server for the live picture:

scripthut status                       # server reachable + auth OK, plus configured sources/backends
scripthut backend list --json          # live connectivity per backend
scripthut source list --json           # sources known to the server
scripthut source view <name> --json    # workflows discovered in a specific source
scripthut stack check --source <name>  # per-backend stack state for repo-defined stacks

The briefing's "Inspecting state" cheat-sheet already lists these, so an agent that's read it will reach for them.

Keeping the briefing trustworthy

The static reference inside the briefing is auto-tested against the actual CLI — there's a regression suite (tests/test_agent_prompt.py) that asserts the commands, flags, and behaviors the briefing teaches still exist. So when ScriptHut adds or renames a subcommand, the briefing fails CI until it's updated. If you spot something stale, re-run scripthut agent prompt after pip install -U scripthut — it'll be current with the installed version.

Tips for productive sessions

  • Run scripthut status first in any new session — if the CLI can't reach the server or auth is broken, nothing the agent does will work, and status produces a clean diagnostic the agent can show you.
  • Use --json everywhere the agent parses output. Every read-only command supports it; the JSON shapes are stable across releases.
  • Capture run IDs explicitly: RUN_ID=$(scripthut task run … --json | jq -r .id) — easier than scraping a human-readable submission summary.
  • For non-trivial tasks, use --dry-run first so the agent can show you the assembled TaskDefinition (resources, env resolution, generated script) before anything submits.