Skip to main content
Automations and Environments work together as a powerful system. Automations can access environment variables, and environments can bundle automations alongside configuration. We recommend reading both pages to understand the full capabilities.

​
Overview

Automations allow you to run custom scripts automatically in response to agent events. Write scripts in Bash, JavaScript, or Python that execute when the agent performs specific actions—like editing files, running commands, or creating commits. Use automations to enforce code quality, run tests, validate changes, integrate with external tools, or orchestrate complex workflows. Scripts have access to rich context about what the agent is doing, including file paths, git diffs, conversation history, and more.

​
Key Concepts

​
Triggers

Automations respond to specific events in your agent’s workflow:
TriggerDescription
ManualRun on demand via command palette
On agent readyExecutes when agent is idle and waiting for input
After edit filesRuns when agent modifies files (optional glob filter)
After read filesTriggers when agent reads files (optional glob filter)
After run commandExecutes after agent runs bash commands (optional regex filter)
Before commitRuns before creating a git commit (always blocking, like a pre-commit hook)
After commitExecutes after a git commit is created
After compactionRuns when conversation history is compacted
After resetTriggers when agent is reset
After automation finishesChains automations together (runs after another automation completes)

​
Script Languages

Choose the language that best fits your task:
  • Bash: Best for shell commands, git operations, file manipulation
  • JavaScript: Ideal for JSON processing, API calls, Node.js tools
  • Python: Great for data processing, testing, complex logic

​
Feed Output to Agent

When enabled, the script’s stdout and stderr are sent to the agent as context. The agent receives the last 1000 lines of output, which helps with debugging and decision-making.

​
Available Variables

VariableTypeDescription
$INPUT_FILE_PATHstringPath of file being edited or read
$INPUT_COMMANDstringBash command being executed
$CURRENT_COMMIT_SHAstringSHA hash of current commit
$CURRENT_COMMIT_CHANGESstringGit diff of current commit
$CURRENT_PENDING_CHANGESstringGit diff of uncommitted changes
$ENTIRE_AGENT_DIFFstringAll changes since agent started
$LAST_PROMPTstringMost recent user prompt
$ALL_LAST_PROMPTSstringAll user prompts (newline-separated)
$CONVERSATION_TRANSCRIPTJSONFull conversation history
$GITHUB_TOKENstringGitHub authentication token (if available)

​
Control Functions

Control functions allow your automation scripts to interact with and control the agent’s behavior. These functions are automatically injected into your script’s runtime environment and can be called directly without any imports or setup.
FunctionParametersDescription
stopAgentNoneImmediately stops the agent execution. Use for critical validation failures.
queuePromptmessage (string)Sends a prompt to the agent programmatically.

​
Example

​
Pre-Commit TypeScript Type Checking

Run TypeScript type checking before every commit and block the commit if there are errors: 
#!/bin/bash
# Trigger: on_before_commit
# Blocking: true
# Feed Output: true

echo "Running TypeScript type checking..."
npx tsc --noEmit

if [ $? -ne 0 ]; then
  echo "❌ TypeScript type check failed - commit blocked"
  stopAgent
  exit 1
fi

echo "✓ TypeScript type check passed"