Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

Nghi D. Q. Bui

cs.AIMar 5, 2026

Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

Authors: Nghi D. Q. Bui

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 $\to$ agent $\to$ workflow $\to$ 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.

Panel of Figure 3 — 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

Appendix

Table 1: Complete catalog of built-in tools in OpenDev (organized by handler category). Tools marked with

\dagger

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

Appendix

Table 2: Supported LSP language servers in OpenDev . Servers marked with

\dagger

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 $\to$ Act $\to$ Observe $\to$ Complete
available-tools	always	✓	Tool category overview and descriptions

Appendix

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 ( $\leq$ 100 words)

Appendix

Table 4: Thinking mode prompt sections (4 sections). All are unconditional and cacheable.

Template	Role	Key Output
compaction.md	Conversation compactor	Structured summary ( $\leq$ 800 words) with artifact index
critique.md	Reasoning critic	Actionable feedback on thinking traces ( $\leq$ 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 ( $\leq$ 100 words)

Appendix

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)

Appendix

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)

Appendix

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

Appendix

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 $\times$ 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)

Appendix

Table 9: Implementation constants in OpenDev with justification.

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

Apr 14, 2026

Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems

Claude Code is an agentic coding tool that can run shell commands, edit files, and call external services on behalf of the user. This study describes its architecture by analyzing the publicly available source code and comparing it with two independent open-source AI agent systems, OpenClaw and Hermes Agent, that answer many of similar or even the same design questions. Our analysis identifies five human values, philosophies, and needs that motivate the architecture: human decision authority, safety, security, and privacy, reliable execution, capability amplification, and contextual adaptability. We then trace them through thirteen design principles to implementation choices. The core of the system is a simple while-loop that calls the model, runs tools, and repeats. Most of the code, however, lives in the systems around this loop: a permission system with seven modes and an ML-based classifier, a five-layer compaction pipeline for context management, four extensibility mechanisms (MCP, plugins, skills, and hooks), a subagent delegation and orchestration mechanism, and append-oriented session storage. Comparisons with OpenClaw and Hermes Agent show that the same design questions produce different answers across three deployment contexts. Claude Code emphasizes per-action safety, OpenClaw emphasizes perimeter-level access, and Hermes renders per-action approvals across many surfaces. At the runtime layer, Claude Code uses a single CLI loop, OpenClaw embeds the runtime within a gateway control plane, and Hermes uses one process whose role is set by its entry point. At the context and extension layer, Claude Code extends the context window, OpenClaw registers gateway-wide capabilities, and Hermes provides pluggable memory and model backends. We finally identify six open design directions for future agent systems, grounded in recent empirical, architectural, and policy literature.

Jiacheng Liu, Xiaohan Zhao, Xinyi Shang +1

VILA Lab, Mohamed bin Zayed University of Artificial Intelligence · University College London

AI Coding Agents LLM Agent Orchestration LLM Agent Security AI Agent Architecture LLM Agent Safety

Ask PDF

Jul 24, 2026

Agent Team Work Zone: An Automated, Persistent Workspace for Long-Lived Claude Code Agent Teams

Large Language Model (LLM) agents have significantly improved coding and programming workflows. Claude Code, in particular, is one of the most powerful LLM coding agents and is capable of conducting complex coding tasks. However, several drawbacks can undermine long-term agentic workflows. (1) Irrecoverable agent teams: The Agent Teams feature is powerful, but the working state accumulated by each teammate is lost and cannot be resumed once the process stops, for example, when a terminal is closed. (2) Compaction erodes working detail: Compaction condenses the conversation into a summary, causing an agent's working details to become vague. (3) Agentic "technical debt": Over time, a user's decisions and the agents' operations become trapped in compacted old chats, making the project increasingly difficult to maintain and review. (4) Heavy prompt writing: Assigning or handing off tasks requires users to repeatedly write long prompts to achieve the expected agentic performance. We propose ATWZ (Agent Team Work Zone), a filesystem-based operations layer built around Claude Code's native Agent Teams that addresses these problems. Its central design principle is to treat each agent and teammate as a human employee and preserve their important working state in files stored in a dedicated directory called a "workstation," together with the skills, hooks, and scripts that use and maintain these files. With ATWZ, an agent team can periodically back up its working state, allowing an agent's knowledge to be recovered after compaction. After a process ends, the team can be restored with a single command. These features also substantially mitigate the agentic "technical debt" described above. Moreover, within ATWZ, agent "employees" can send documents to one another, greatly reducing the effort required to write prompts.

Shouren Wang

Case Western Reserve University

LLM Agent Memory LLM Agent Workflow Optimization Long-Horizon LLM Agents Multi-Agent Coding LLM Agent Harnesses

Ask PDF

Sep 21, 2026

A Lean and Spec-Driven AI-Assisted Software Development Lifecycle for Applied AI Education: The AI-SDLC Approach

AI coding agents increasingly support software development beyond code completion, including planning, implementation, testing, and repository-level task execution. Their practical use, however, often remains only weakly connected to established software engineering practices. The aim of this work is to develop and evaluate a lightweight, spec-driven lifecycle for governed agentic software engineering. The lifecycle combines established software engineering practices with repository-local guidance through specifications, AGENTS.md, and phase-specific agent skill files. The approach was developed in the context of the FHNW course AI-assisted Software Development and applied by students to business-oriented software use cases. Its educational and practical applicability is explored through a student survey combining closed rating items with open-ended questions. The contribution of this work is a process-oriented framework that enables AI coding agents to operate with bounded autonomy within an explicit, reviewable, and test-oriented software development lifecycle.

Andreas Martin, Sandro Schwander

FHNW University of Applied Sciences and Arts Northwestern Switzerland, School of Business, Riggenbachstrasse 16, 4600 Olten, Switzerland

AI-Assisted Software Development Software Engineering Automated Software Engineering AI Coding Agents AI in Education

Ask PDF

Abstract

AI Coding Agents

Explore similar work

Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems

Agent Team Work Zone: An Automated, Persistent Workspace for Long-Lived Claude Code Agent Teams

A Lean and Spec-Driven AI-Assisted Software Development Lifecycle for Applied AI Education: The AI-SDLC Approach