Scripting

Overview

Armament’s scripting engine is modeled after IRC clients — lightweight, declarative, and composable. Scripts live in ~/.armament/scripts/ and use the .arma extension. These scripts handle UX, configuration, shortcuts, and event-driven automation.

For multi-agent workflow orchestration, see Workflow Orchestration.

Script Structure

# Comments start with #
# Commands are slash-prefixed directives

/alias gpt /model gpt-4
/alias opus /model claude-opus
/alias fast /route complexity=low model=gpt-4-turbo

/trigger /error|exception|traceback/ /agent focus $agent && /view focus
/trigger /all tests passing/ /theme green && /timer celebrate 3s /theme red

/bind ctrl+g /git status
/bind ctrl+shift+r /session checkpoint && /config reload

/timer healthcheck 60s /health
/timer budget-warn 300s /budget

Commands Reference

Aliases

Aliases expand to commands. Arguments are passed through with $1, $2, $*:

/alias deploy /agent assign deployer "deploy $1 to $2"
/alias review /route task=review model=claude-opus file=$1
/alias quick /route complexity=low model=gpt-4-turbo $*

Usage:

/deploy backend production
# Expands to: /agent assign deployer "deploy backend to production"

Triggers

Triggers watch all output for regex patterns and fire actions when matched:

/trigger /budget.*warning/ /session pause
/trigger /agent-(\d+) completed/ /agent kill $1
/trigger /conflict detected in (.+)/ /git resolve $1

Capture groups are available as $1, $2, etc.

Trigger Flags

/trigger:once /setup complete/ /theme synthwave
/trigger:silent /heartbeat/ /log debug heartbeat-ok

• :once — fires once then removes itself
• :silent — no notification in the activity feed

Keybindings

Bind key sequences to commands:

/bind ctrl+1 /agent focus 1
/bind ctrl+2 /agent focus 2
/bind ctrl+shift+n /agent new
/bind alt+t /theme cycle
/bind F5 /session checkpoint

Modifier keys: ctrl, alt, shift, meta. Combinable with +.

Timers

Repeating timers execute on intervals:

/timer status 30s /session
/timer cost-check 120s /cost
/timer auto-save 300s /session checkpoint

Interval formats: 10s, 5m, 1h.

One-shot Timers

/timer:once reminder 1h /notify "Time to review progress"

Variables

Scripts can set and read variables using /set and /unset. Variable interpolation uses $varname syntax with dot-notation support:

/set default_model claude-opus
/set project_budget 100

/alias switch-model /model $default_model

Dot-notation access:

/set greeting "Hello from $agent.name running $agent.model"

Escape with \$ to suppress interpolation.

Built-in Variables

Conditionals

/if $budget_used > 40
  /theme red
  /notify "Budget running high"
/elif $budget_used > 20
  /theme yellow
/else
  /theme green
/endif

Loops

Foreach

/foreach $file in src/*.ts
  /agent assign reviewer "review $file"
/endfor

Repeat

/repeat 3
  /agent new worker
/endrepeat

While

/while $agents_running < 5
  /agent new worker
/endwhile

Macros

Define reusable blocks with /define and invoke them with /call:

/define setup-reviewers
  /agent new reviewer-1
  /agent new reviewer-2
  /set review_mode active
  /theme synthwave
/enddefine

/call setup-reviewers

Macros accept arguments:

/define deploy-to
  /agent assign deployer "deploy $1 to $2"
  /notify "Deploying $1 to $2..."
/enddefine

/call deploy-to backend production

Event Handlers

React to system events with /on blocks:

/on agent:complete
  /notify "$agent.name finished"
  /agent kill $agent
/endon

/on budget:warning
  /route default=cost-optimized
  /theme red
/endon

/on session:idle 5m
  /session checkpoint
/endon

Try/Catch

Handle errors gracefully:

/try
  /agent assign builder "compile project"
/catch
  /notify "Build failed — reassigning"
  /agent assign fixer "fix build errors"
/endtry

Font and Accessibility

Configure font rendering directly from scripts:

/font size 16
/font family "JetBrains Mono"
/font zoom-in
/font zoom-out
/font reset

Display Configuration

Toggle display behaviors:

/display compact on
/display timestamps on
/display syntax-highlighting on

Including Other Scripts

Split configurations across files:

/include ~/.armament/scripts/keybindings.arma
/include ~/.armament/scripts/aliases.arma

Loading Scripts

Scripts auto-load from ~/.armament/scripts/ on boot. Manual loading:

/script load ~/custom/workflow.arma

Project-local scripts in .armament/scripts/ load when you enter the project directory.

Script API (Advanced)

For programmatic scripting, .arma.js files have access to the ViewAPI:

// ~/.armament/scripts/custom-monitor.arma.js
export default function(api) {
  api.on('agent:complete', (event) => {
    if (event.agent.tasks.length === 0) {
      api.exec('/agent kill ' + event.agent.id);
      api.notify('Agent ' + event.agent.id + ' finished and cleaned up');
    }
  });

  api.on('budget:warning', () => {
    api.exec('/route default=cost-optimized');
    api.exec('/theme red');
  });
}

ViewAPI Methods