@elizaos/plugin-code

A unified code toolkit for elizaOS that provides filesystem, shell, git, and AI-powered coding capabilities.

Features

Core File Operations

• Read, Write, Edit: Full file manipulation
• List, Search: Directory browsing and content search
• Shell Execution: Run commands in a sandboxed directory
• Git Commands: Execute git operations
• Safety Controls: Path validation, command filtering, forbidden command blocking

AI Coding Agents

• Native Agent: Uses elizaOS LLM + file actions (always available)
• Claude Code: Anthropic's official CLI (recommended)
• Cursor Agent: Cursor IDE agent with stream-json output
• Aider: AI pair programming in terminal
• Codex: OpenAI's official CLI
• OpenCode: Multi-provider coding assistant

Learning & Stats

• Lessons: Track failures and learn from them
• Stats: Monitor agent performance over time
• Dynamic Providers: Multi-resolution context for LLM prompts

Installation

bun add @elizaos/plugin-code

Configuration

Core Settings

Variable	Description	Required	Default
CODER_ENABLED	Enable/disable the plugin	No	false
CODER_ALLOWED_DIRECTORY	Directory for operations	Yes	process.cwd()
CODER_TIMEOUT	Command timeout (ms)	No	30000
CODER_FORBIDDEN_COMMANDS	Additional forbidden commands	No	-

AI Agent Settings

Variable	Description	Values	Default
CODE_MODE	Agent selection mode	auto, native, cli	auto
CODE_CLAUDE_MODEL	Model for Claude Code	Model name	-
CODE_CURSOR_MODEL	Model for Cursor	Model name	-
CODE_AIDER_MODEL	Model for Aider	Provider/model	-
CODE_CODEX_MODEL	Model for Codex	Model name	-
CODE_OPENCODE_MODEL	Model for OpenCode	Model name	-

CODE_MODE Values

• auto (default): Use CLI agent if available, otherwise native
• native: Always use elizaOS native coding (LLM + file actions)
• cli: Always use CLI agents (error if none available)

Usage

import { coderPlugin } from '@elizaos/plugin-code';

// Add to your agent's plugins
const agent = {
  plugins: [coderPlugin],
  // ...
};

Actions

File Operations

Action	Description	Similes
READ_FILE	Read file contents	VIEW_FILE, OPEN_FILE, CAT_FILE
WRITE_FILE	Create or overwrite a file	CREATE_FILE, SAVE_FILE
EDIT_FILE	Replace substring in file	REPLACE_IN_FILE, PATCH_FILE
LIST_FILES	List directory contents	LS, LIST_DIR
SEARCH_FILES	Search text in files	GREP, FIND_IN_FILES
CHANGE_DIRECTORY	Change working directory	CD, CWD
EXECUTE_SHELL	Run shell command	SHELL, RUN_COMMAND, EXEC
GIT	Run git command	GIT_COMMAND

AI Coding Actions

Action	Description	Availability
CODE	Execute with best agent	Always
CLAUDE_CODE	Execute with Claude Code	If CLI detected
CURSOR	Execute with Cursor	If CLI detected
AIDER	Execute with Aider	If CLI detected
CODEX	Execute with Codex	If CLI detected
OPENCODE	Execute with OpenCode	If CLI detected
DETECT_AGENTS	List available agents	Always

Learning Actions

Action	Description
VIEW_LESSONS	Show failure history
SHOW_STATS	Show agent performance

Providers

Core Providers

Provider	Description
CODER_STATUS	Current directory, history, recent operations
CODE_HELP	Usage instructions for the agent to guide users
CODE_SETTINGS	Current configuration (mode, agents, directories)

Execution Status (for Orchestrator)

Provider	Description
CODE_EXECUTION_STATUS_OVERVIEW	One-line: CODE_STATUS: writing | agent=claude-code | progress=45%
CODE_EXECUTION_STATUS	Structured status with files read/written
CODE_EXECUTION_STATUS_FULL	Complete with action history (CSV)

Why Execution Status? The orchestrator needs visibility into what's happening during code execution:

• Progress based on actual file activity (not guessing)
• User sees "Writing src/auth.ts..." instead of "Running..."
• Smart decisions: retry on error, adjust timeout

Dynamic Multi-Resolution Providers

Provider	Resolution	Description
CODE_AGENTS_OVERVIEW	Low	Agent count and names
CODE_AGENTS	Medium	CSV: name, available, recommended
CODE_AGENTS_FULL	High	Full agent details
CODE_LESSONS_OVERVIEW	Low	Lesson count
CODE_LESSONS	Medium	CSV of recent lessons
CODE_LESSONS_FULL	High	Full lesson details
CODE_STATS_OVERVIEW	Low	Best agent, success rate
CODE_STATS	Medium	CSV per agent
CODE_STATS_FULL	High	Detailed breakdown

All dynamic providers are marked dynamic: true and not auto-included in prompts.

How CODE_MODE Works

User: "fix the bug in utils.ts"
       |
       v
   CODE action
       |
       v
  Check CODE_MODE
       |
   +---+---+
   |       |
  auto   native/cli
   |       |
   v       v
Prefer CLI → Native fallback
   |
   v
Execute with selected agent
   |
   v
Return result (success/failure)

Storage

Lessons and stats are stored on disk in the project directory:

• .plugin-code/lessons.json - Failure history
• .plugin-code/stats.json - Performance stats

This enables persistence across restarts and sharing between sessions.

Security

The plugin implements several security measures:

1. Path Validation: All file operations restricted to CODER_ALLOWED_DIRECTORY
2. Command Filtering: Blocks shell control operators (&&, ||, ;, $(, backticks)
3. Forbidden Commands: Blocks dangerous commands like rm -rf /, sudo rm, etc.
4. Timeout: Commands killed after CODER_TIMEOUT milliseconds
5. Disabled by Default: Must explicitly set CODER_ENABLED=true

Architecture

plugin-code
├── Services
│   ├── CoderService              # File ops, shell, working directory
│   ├── AgentRegistry             # Manages all coding agents
│   ├── ExecutionTrackerService   # Tracks execution status per conversation
│   ├── LessonsService            # Tracks failures
│   └── StatsService              # Tracks performance
├── Agents
│   ├── NativeCoderAgent    # elizaOS LLM + file actions
│   ├── ClaudeCodeAgent     # Claude Code CLI
│   ├── CursorAgent         # Cursor Agent CLI
│   ├── AiderAgent          # Aider CLI
│   ├── CodexAgent          # Codex CLI
│   └── OpenCodeAgent       # OpenCode CLI
├── Actions
│   ├── File ops            # read, write, edit, etc.
│   ├── Agent actions       # CODE, CLAUDE_CODE, etc.
│   └── PRR actions         # VIEW_LESSONS, SHOW_STATS
└── Providers
    ├── coderStatusProvider     # Core status
    ├── help.provider           # Usage instructions
    ├── settings.provider       # Configuration
    ├── executionStatus.provider # 3 resolutions (for orchestrator)
    ├── agents.providers        # 3 resolutions
    ├── lessons.providers       # 3 resolutions
    └── stats.providers         # 3 resolutions

Integration with plugin-orchestrator

This plugin works standalone, but also integrates seamlessly with plugin-orchestrator:

• Standalone: User says "fix bug" → CODE action → done
• With Orchestrator: Orchestrator calls CODE action as part of complex task workflow

The CODE action executes once and returns - retries, task lifecycle, and notifications are handled by the orchestrator.

License

MIT