A minimalist AI Agent development platform - Build AI agents the Unix way
Delta lets you create AI agents the simplest way possible: all capabilities are external commands, all interactions go through the file system, and all state can be resumed anytime.
# 1. Install
npm install -g delta-engine
# 2. Create your first agent
delta init my-agent -t hello-world
# 3. Run it
delta run --agent ./my-agent -m "Create a greeting file"What just happened?
- Agent read your task
- Used LLM to think about what to do
- Executed commands like
echoandlsto complete the task - Logged everything to
.delta/journal.jsonl
Try more:
# Let the agent analyze data with Python
delta run --agent ./my-agent -m "Calculate the sum of squares from 1 to 100"
# Resume anytime after interruption (run after Ctrl+C)
delta run --agent ./my-agent -m "Same task" # Auto-resume from checkpointLet agents execute system commands, analyze logs, generate reports
Example: hello-world - Simple agent using basic Unix commands
Create persistent Shell/Python REPL environments that maintain state across commands
Example: interactive-shell - Persistent bash session management Example: python-repl - Python REPL with state persistence
Learn different ways to configure agent tools with various execution modes
Example: tool-syntax - Demonstration of exec and shell modes
Create meta-agents that can invoke other agents for complex multi-step workflows
Example: delta-agent-generator - Agent that generates agents
| Feature | Delta Engine | Traditional Frameworks |
|---|---|---|
| Capability Extension | Write any shell script | Requires framework plugin code |
| State Management | Fully stateless, resumable | Memory-dependent, fails on interrupt |
| Debugging | Read .delta/journal.jsonl directly |
Requires specialized debugging tools |
| Learning Curve | Command-line knowledge sufficient | Must learn framework APIs |
| Tool Reuse | All Unix tools work directly | Need to re-wrap existing tools |
- Ultimate Simplicity: All agent capabilities are external commands (
ls,cat,python, etc.) - no framework API to learn - Complete Transparency: All execution details logged in
.delta/directory - inspect, analyze, trace anytime - Perfect Resumability: Resume from any interruption (Ctrl+C, power loss, crash)
- ✅ Comfortable with command-line tools, want to quickly build AI agents
- ✅ Need agents to execute long-running tasks that may be interrupted
- ✅ Require complete audit logs and execution records
- ✅ Want agents to invoke any existing command-line tools
- ✅ Need human-in-the-loop reviews during agent execution
Delta is built on three core principles (Three Pillars):
All agent capabilities are implemented through external commands, with no built-in functions.
# agent.yaml - Define what your agent can do
tools:
- name: list_files
exec: "ls -la ${directory}"
- name: analyze_data
shell: "python analyze.py ${data_file} | tee report.txt"Any command-line tool (grep, awk, docker, custom scripts) can directly become an agent capability.
Agents interact with the world through their working directory (CWD) - the file system is the universal interface.
my-agent/workspaces/W001/ ← Agent's working directory
├── input.txt ← Input files
├── output.json ← Agent-generated results
├── DELTA.md ← Dynamic instructions for agent
└── .delta/ ← Control plane (logs, state)
├── journal.jsonl ← Complete execution history
└── metadata.json ← Run status
All data is visible, modifiable, version-controllable - agent execution is completely transparent.
Complex agent behaviors emerge from composing simple, single-purpose agents - not from building monolithic systems.
# Meta-agent that orchestrates other agents
tools:
- name: data_agent
exec: "delta run --agent ./data-analyzer -m ${task}"
- name: writer_agent
exec: "delta run --agent ./report-writer -m ${task}"Build sophisticated AI systems like LEGO blocks - each agent does one thing well, composition creates intelligence.
Resume seamlessly from any interruption (Ctrl+C, crash, shutdown):
delta run --agent ./my-agent -m "Long-running task"
# Execution interrupted...
delta run --agent ./my-agent -m "Long-running task" # Auto-continueAgent can ask you questions mid-execution and wait for your reply:
delta run -i --agent ./my-agent -m "Task requiring confirmation"
# Agent: "Delete these files? [yes/no]"
# You type answer, agent continuesCreate persistent Shell/REPL environments with delta-sessions:
delta-sessions start bash # Create bash session
echo "cd /data && ls" | delta-sessions exec <session_id>
# Working directory persists at /dataCompress conversation history with external scripts for long-term tasks:
# context.yaml - Define context composition strategy
sources:
- type: computed_file
generator:
command: ["python", "tools/summarize.py"] # Compress history
output_path: ".delta/context_artifacts/summary.md"
- type: journal
max_iterations: 5 # Keep only last 5 full conversation roundsInject custom logic at critical moments:
# hooks.yaml - Separate lifecycle hooks configuration (v1.9+)
pre_llm_req:
command: ["./check-budget.sh"] # Check budget before each LLM call
post_tool_exec:
command: ["./log-to-audit.sh"] # Log to audit after each tool execution
on_run_end:
command: ["./cleanup.sh"] # Cleanup when run completes (v1.9 new)- Quick Start - 5-minute tutorial to create your first agent
- hello-world example - Understand Delta's three pillars
- tool-syntax example - Learn tool configuration modes
- Agent Development Guide - Complete agent development guide
- interactive-shell example - Learn session management
- python-repl example - Python REPL with state persistence
- Context Management Guide - Learn context composition strategies
- Hooks Guide - Learn lifecycle hooks and extensibility
- Architecture Overview - Understand system design principles
- delta-agent-generator example - Advanced AI-orchestrating-AI patterns
- All Examples - 5 focused examples demonstrating core capabilities
- API Reference - Complete CLI commands and configuration format docs
- Architecture Docs - Design philosophy and technical details
# Initialize
delta init <agent-name> -t <template> # Create from template
delta init <agent-name> # Blank agent
# Run
delta run --agent <path> -m "Task description" # Basic run
delta run -i --agent <path> -m "..." # Interactive mode
delta run -y --agent <path> -m "..." # Silent mode (auto-create workspace)
# Version info
delta --version
# Session management
delta-sessions start [shell] # Create session (default: bash)
delta-sessions exec <session_id> # Execute command (read from stdin)
delta-sessions end <session_id> # Terminate session
delta-sessions list # List all sessions# View run status
RUN_ID=$(cat .delta/LATEST)
cat .delta/$RUN_ID/metadata.json
# View execution history
tail -50 .delta/$RUN_ID/journal.jsonl
# View LLM invocation logs
ls -lht .delta/$RUN_ID/io/invocations/ | head -5
# View tool execution logs
ls -lht .delta/$RUN_ID/io/tool_executions/ | head -5
# Check pending human interactions
ls -la .delta/interaction/my-agent/
├── agent.yaml # Required: Agent config (LLM, tools) [v1.9+]
├── hooks.yaml # Optional: Lifecycle hooks [v1.9+]
├── system_prompt.md # Required: System prompt (can be .txt)
├── context.yaml # Optional: Context composition strategy
├── modules/ # Optional: Reusable tool modules [v1.9+]
│ ├── file-ops.yaml
│ └── web-search.yaml
├── tools/ # Optional: Custom tool scripts
│ ├── analyze.py
│ └── summarize.sh
└── workspaces/ # Runtime generated: Execution workspaces
├── LAST_USED # Tracks last used workspace
├── W001/ # Workspace 1 (sequential numbering)
│ ├── DELTA.md # Optional: Workspace-level context
│ ├── [your files] # Files agent operates on
│ └── .delta/ # Control plane
│ ├── VERSION # Data format version
│ ├── LATEST # Latest run ID
│ └── <run_id>/ # Single run records
│ ├── journal.jsonl # Execution log (core)
│ ├── metadata.json # Run metadata
│ ├── engine.log # Engine logs
│ └── io/ # I/O audit
│ ├── invocations/ # LLM invocations
│ ├── tool_executions/ # Tool executions
│ └── hooks/ # Hook executions
└── W002/ # Workspace 2
Note: config.yaml still supported for backward compatibility (v1.9)
# Method 1: exec - Direct execution (recommended, safest)
- name: list_files
exec: "ls -F ${directory}"
# Method 2: shell - Shell interpretation (for pipes, redirects)
- name: count_lines
shell: "cat ${file} | wc -l"
# Using stdin parameter
- name: write_file
exec: "tee ${filename}"
stdin: content # content parameter injected via stdin
# :raw modifier (for passing flag lists)
- name: run_docker
shell: "docker run ${flags:raw} ${image}"
# LLM passes: flags="-p 8080:80 -d"
# Actual execution: docker run -p 8080:80 -d nginx
# Full syntax (complex scenarios)
- name: search
command: [grep, -r]
parameters:
- name: pattern
type: string
inject_as: argument
- name: directory
type: string
inject_as: argument- Node.js 20+
- TypeScript 5+ (development only)
- OS: Linux / macOS / WSL
- Current Version: v1.10.0
- License: MIT
- Repository: GitHub
- Issue Tracker: Issues
- Contributing: CONTRIBUTING.md
- Changelog: CHANGELOG.md
- Documentation: docs/
- Examples: examples/
- Discussions: GitHub Discussions
- Blog: See
docs/architecture/philosophy-02-whitepaper.mdfor design philosophy