cs.AIMar 5, 2026
SaveBuilding Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned
Organizations: OpenDev
Abstract
The landscape of AI coding assistance is undergoing a fundamental shift from complex IDE plugins to versatile, terminal-native agents. Operating directly where developers manage source control, execute builds, and deploy environments, CLI-based agents offer unprecedented autonomy for long-horizon development tasks. In this paper, we present OPENDEV, an open-source, command-line coding agent written in Rust, engineered specifically for this new paradigm. Effective autonomous assistance requires strict safety controls and highly efficient context management to prevent context bloat and reasoning degradation. OPENDEV overcomes these challenges through a compound AI system architecture with workload-specialized model routing, a dual-agent architecture separating planning from execution, lazy tool discovery, and adaptive context compaction that progressively reduces older observations. Furthermore, it employs an automated memory system to accumulate project-specific knowledge across sessions and counteracts instruction fade-out through event-driven system reminders. By enforcing explicit reasoning phases and prioritizing context efficiency, OPENDEV provides a secure, extensible foundation for terminal-first AI assistance, offering a blueprint for robust autonomous software engineering.
Figures & tables
Figure 1: Overview of OpenDev . Work is organized into concurrent sessions, each composed of multiple specialized sub-agents; each agent executes typed workflows (Execution, Thinking, Compaction) that independently bind to a user-configured LLM. This four-level hierarchy (session agent workflow LLM) enables fine-grained model selection, allowing cost, latency, and capability trade-offs to be optimized per workflow.
Figure 2: System architecture of OpenDev , organized into four layers: Entry & UI, Agent, Tool & Context, and Persistence. Arrows indicate primary data-flow directions.
Figure 3: Defense-in-depth safety architecture. Five independent layers intercept dangerous actions at progressively lower levels of abstraction, from model reasoning (Layer 1) to user-defined scripts (Layer 5). Each layer operates independently; failure of any single layer does not compromise the remaining four.
Figure 4: The agent harness architecture: a detailed view of the Agent layer from Figure 2 . The central ReAct loop (six phases: pre-check and compaction, thinking, self-critique, action, tool execution, post-processing) is surrounded by seven supporting subsystems. User messages enter through a message injection queue (top). The Prompt Composition engine assembles modular sections by priority into the system prompt. The Tool Registry dispatches to specialized handlers, with MCP tools discovered lazily. The Safety System enforces multiple independent layers (approval, dangerous command detection, hooks, stale-read detection, plan mode restrictions, doom loop detection, iteration cap, cooperative cancellation). Context Engineering applies five-stage progressive compaction as the conversation grows. Memory and Session services provide persistent strategy memory (playbook), session storage, and per-step undo via git snapshots. Subagent Orchestration spawns isolated agent instances with filtered tool access for parallel exploration or specialized tasks.
Figure 5: Dual-mode operation within the Agent layer ( Figure 4 ). A user prompt enters the MainAgent , which routes to either Plan Mode (left, read-only) or Normal Mode (right, full access). Plan Mode spawns a Planner subagent that explores the codebase, analyzes patterns, and produces a structured plan for user approval. Upon approval, the system transitions to Normal Mode, where the agent executes the planned steps with full tool access. The user can re-enter Plan Mode at any point if unexpected results require re-planning.
Figure 6: Sequence diagram of a single conversation turn in OpenDev . A user message enters through one of three interfaces, passes through query processing, and enters the ReAct iteration loop. Each iteration comprises context management, optional thinking, an action LLM call, and tool dispatch through the registry. The loop continues until the agent signals completion or a termination condition is met, after which the conversation state is persisted.
Figure 7: Dual-path input dispatch in OpenDev . User input is classified at the REPL boundary: slash commands (top path) are routed through the REPL Command Dispatcher to one of nine registered command handlers, each of which modifies system state directly and returns a CommandResult . Natural language queries (bottom path) pass through the Query Processor into the Agent Loop, which interacts with system state through tool execution. Both paths ultimately produce side effects on shared system state, but through fundamentally different mechanisms: commands execute deterministically without LLM involvement, while queries are processed through the full reasoning loop.
Figure 8: Detailed view of the ReAct loop at the center of Figure 4 . Each user query passes through an initialization stage that creates an IterationContext , then enters an iteration loop ( _run_iteration_inner ) consisting of four phases: context management, thinking, action, and decision. The loop continues until the agent produces a final response, explicitly signals completion, or exhausts its iteration budget.
Figure 9: Expanded view of the Tool & Context layer from Figure 2 . Six subsystems cooperate to fill and maintain the model’s context window across a session. The subsystems are presented in lifecycle order: dynamic system prompt construction initializes behavioral instructions; dual-memory and tool result optimization shape what enters the context; system reminders and error recovery inject targeted guidance at runtime; and adaptive context compaction manages overflow when the token budget nears exhaustion.
Figure 10: Detailed view of the prompt composition subsystem from Figure 9 . Sections are registered with optional condition predicates and priority values. At agent initialization the PromptComposer evaluates each predicate against the runtime environment, sorts surviving sections by ascending priority, loads their markdown templates, and joins them into the final system prompt. Four logical tiers, Core Identity, Tool Definitions, Safety & Rules, and Dynamic Context, which organize sections by function. Dashed borders indicate conditionally loaded sections that are included only when their predicate is satisfied.
Figure 11: Detailed view of the reminder subsystem from Figure 9 . Without reminders (left), an agent with one incomplete todo declares completion, forcing the user to intervene and causing a loss of trust. With reminders (right), the ReactExecutor detects the unfinished state, injects a targeted user-role message listing the outstanding item, and the agent resumes work and completes the task correctly.
Figure 12: Architecture of the Reminder Injection Layer. After each iteration of the ReAct Executor Loop (top), eight event detectors examine the conversation state. When a detector fires, the corresponding reminder template is resolved via get_reminder() from reminders.md (with .txt fallbacks for longer prompts), checked against guardrail counters that cap how many times each reminder can fire, and appended to the message list as a role: user message. The next LLM call sees this reminder as the most recent input, maximizing its influence on the model’s next decision.
Figure 13: Detailed view of the compaction subsystem from Figure 9 . Five stages activate at progressive pressure thresholds (70%, 80%, 85%, 90%, 99%), transitioning observations between active, faded, and archived states before emergency summarization is required.
Figure 14: Detailed view of the memory subsystem from Figure 9 . Stage 1: the BulletSelector scores playbook bullets by effectiveness, recency, and semantic similarity to the current query, and the selected bullets are injected into the Generator’s system prompt alongside the user query. Stage 2: an episodic memory mechanism triggers the Reflector every five messages of interaction; the Reflector analyzes accumulated experience and produces a reasoning trace, error identification, root-cause analysis, and correct approach. Stage 3: a Curator reads the reflection and plans concrete playbook mutations (add, update, tag, or remove bullets). Stage 4: the mutations are applied to the Playbook’s bullet table and persisted to a session-scoped JSON file.
Figure 15: End-to-end synthesis of the retrieval and context components from Figure 9 . Four layers transform a user query into a fully assembled LLM API call: (1) retrieval tools gather raw code artifacts, (2) the Code Explorer subagent orchestrates multi-step searches in an isolated context, (3) the context assembler merges retrieved material with conversation history and system instructions, and (4) the context optimizer enforces the token budget through staged compaction before the final API call.
Figure 16: Expanded view of the Tool layer from Figure 2 . ToolSchemaBuilder assembles JSON schemas from three sources (static built-in definitions, dynamically discovered MCP tools, subagent schemas) and injects them into the LLM prompt. ToolRegistry dispatches tool calls to category-based handlers, each receiving a ToolExecutionContext with cross-cutting services. Pre/post lifecycle hooks intercept calls for safety enforcement and extensibility.
Figure 17: Detailed pipeline for the Process handler ( Figure 16 ). Commands pass through three safety gates (permission config, allowed-command matching, dangerous pattern blocking), then command preparation (auto-confirm, unbuffered Python), server detection (regex match against 16 patterns for auto-background promotion), execution fork (PTY-based background or piped foreground with process-group isolation), output management (30k char limit with head/tail truncation, 100ms polling), and timeout/interrupt handling (60s idle, 600s absolute, InterruptToken integration).
Figure 18: Detailed architecture for the Symbols handler ( Figure 16 ). The system is organized into four layers: Agent Tool Layer (six symbol tools), Symbol Retriever (unified API), LSP Server Wrapper (language detection, per-language server pool, symbol conversion), and Solid Language Server (two-level cache, file buffer management, LSP protocol operations). The Language Server Handler manages subprocess lifecycle and JSON-RPC 2.0 communication with external language server processes. Language detection maps 30+ file extensions to their respective servers, which are started lazily on first query and reused across subsequent requests.
Figure 19: Sequence within the Tool layer ( Figure 16 ). The LLM issues a search_tools call with a natural-language query. The SearchToolsHandler builds a keyword vocabulary from all registered MCP tool names and descriptions, scores each tool against the query, and returns top matches. The ToolRegistry marks matched tools as discovered, including their schemas in subsequent LLM calls. Only discovered tools incur schema cost, reducing baseline token overhead of MCP integration to near zero.
Appendix figures & tables9 assets
Supplementary material from the paper’s appendix.
Appendix
| Category | Tool | Description |
|---|---|---|
| File Ops | read_file † | Read file contents with line-numbered output and optional offset/limit |
| write_file | Create new files (rejects overwrites; directs to edit_file ) | |
| edit_file | Apply targeted edits via 9-pass fuzzy matching chain | |
| list_files † | Directory listing and glob-based file search | |
| search † | Dual-mode search: regex (ripgrep) or structural (ast-grep) | |
| Process | run_command | Execute shell commands with auto-background for servers |
Table 1: Complete catalog of built-in tools in OpenDev (organized by handler category). Tools marked with are read-only and available in plan mode.
| Language | Server | Language | Server |
|---|---|---|---|
| Python | Pyright | Perl | Perl::LanguageServer |
| TypeScript/JS | tsserver | Clojure | clojure-lsp |
| Rust | rust-analyzer | Elm | elm-language-server |
| Go | gopls | Terraform | terraform-ls |
| Java | Eclipse JDT LS | Bash | bash-language-server |
| C/C++ | clangd | Nix | nixd |
Table 2: Supported LSP language servers in OpenDev . Servers marked with are experimental and must be explicitly specified. Alternative servers for the same language (e.g., Jedi for Python, Solargraph for Ruby) are omitted.
| Section | Condition | Cache | Summary |
|---|---|---|---|
| mode-awareness | always | ✓ | Guides planner subagent usage for non-trivial tasks |
| security-policy | always | ✓ | Authorized security testing boundaries |
| tone-and-style | always | ✓ | Communication standards: concise, direct, no emojis |
| no-time-estimates | always | ✓ | Never provide duration estimates |
| interaction-pattern | always | ✓ | ReAct loop: Think Act Observe Complete |
| available-tools | always | ✓ | Tool category overview and descriptions |
Table 3: Complete registry of main agent prompt sections (21 sections). Conditions: always = unconditional; others evaluate a runtime context predicate. Cache: whether the section is included in the stable (cacheable) partition for Anthropic prompt caching.
| Section | Summary |
|---|---|
| thinking-available-tools | Tool awareness without invocation pressure |
| thinking-subagent-guide | Delegation reasoning: when and which subagent |
| thinking-code-references | Code reference format for navigation |
| thinking-output-rules | No actions, only reasoning; concise trace ( 100 words) |
Table 4: Thinking mode prompt sections (4 sections). All are unconditional and cacheable.
| Template | Role | Key Output |
|---|---|---|
| compaction.md | Conversation compactor | Structured summary ( 800 words) with artifact index |
| critique.md | Reasoning critic | Actionable feedback on thinking traces ( 100 words) |
| init.md | Session initializer | OPENDEV.md generation via Code-Explorer |
| main.md | Core identity wrapper | Senior engineer persona with full tool access |
| thinking.md | Thinking wrapper | Concise internal reasoning trace ( 100 words) |
Table 5: Specialized prompt templates (not auto-registered).
| # | Regex Pattern | Framework |
|---|---|---|
| 1 | flask\s+run | Flask |
| 2 | python.*app.py | Generic Python app |
| 3 | python.*manage.py\s+runserver | Django (manage.py) |
| 4 | django.*runserver | Django (direct) |
| 5 | uvicorn | Uvicorn (ASGI) |
| 6 | gunicorn | Gunicorn (WSGI) |
Table 6: Server detection patterns for automatic background promotion.
| Subagent | Tools Available | Use Case |
|---|---|---|
| Code-Explorer | read_file, search, list_files, find_symbol, find_referencing_symbols | Deep codebase exploration, architectural analysis, pattern discovery |
| Planner | All read-only + write_file, edit_file, spawn_subagent, ask_user, task_complete | Implementation planning with codebase analysis and plan file writing |
| PR-Reviewer | read_file, search, list_files, find_symbol, find_referencing_symbols, run_command | Pull request code review, diff analysis, pre-merge review |
| Security-Reviewer | read_file, search, list_files, find_symbol, find_referencing_symbols, run_command | Security audits, vulnerability assessment, severity/confidence scoring |
| Web-Clone | capture_web_screenshot, analyze_image, write_file, read_file, run_command, list_files | Visual website analysis and UI replication |
| Web-Generator | write_file, edit_file, run_command, list_files, read_file | Create web applications from specifications (React/TypeScript/Tailwind) |
Table 7: Subagent types with tool access and use cases. Tool counts reflect the filtered registry; the main agent has access to all 35 built-in tools.
| Field | Type | Description |
|---|---|---|
| model | str | LLM model identifier |
| provider | str | API provider (openai, azure, etc.) |
| max_context_tokens | int | Max context window size |
| temperature | float | LLM sampling temperature |
| max_tokens | int | Max response tokens |
| thinking_model | str | Model for thinking phase |
Table 8: Key configuration fields in OpenDev .
| Constant | Value | Rationale |
|---|---|---|
| Compaction stages | 70/80/90/99% | Four graduated thresholds: warn, mask, aggressive mask, full compaction |
| Max undo history | 50 ops | Bounded growth prevents OOM in long sessions |
| Max nudge attempts | 3 | Balance recovery opportunity vs. forcing progress |
| Doom-loop threshold | 3 repeats | Same (tool, args) fingerprint 3 in sliding window triggers warning |
| Doom-loop window | 20 calls | Sliding window of recent tool call fingerprints |
| Thinking levels | 4 (OFF–HIGH) | OFF, LOW, MEDIUM, HIGH (includes self-critique) |
Table 9: Implementation constants in OpenDev with justification.
More in this topic
AI Coding Agents
AI coding agents use language models and software tools to plan, edit, test, and maintain code with varying levels of autonomy.
See all 326 papers