6. Key Files Map

Essential Files to Understand the System

Tier 1: Core Architecture (Must Read)

File	Lines	Responsibility
`openhands/controller/agent_controller.py`	1392	Central orchestrator: main loop, state management, delegation, stuck detection, security checks
`openhands/controller/agent.py`	191	Abstract base agent with registry pattern
`openhands/agenthub/codeact_agent/codeact_agent.py`	~317	Primary agent: LLM calling, tool assembly, action conversion
`openhands/events/stream.py`	291	Event bus: persistence, subscriptions, secret redaction, async dispatch
`openhands/events/event.py`	122	Event base class: ID, timestamp, source, causality
`openhands/llm/llm.py`	874	LLM wrapper: provider abstraction, retry, metrics, caching, function calling
`openhands/runtime/base.py`	1348	Abstract runtime: sandbox interface for code execution

Tier 2: LLM & Prompting (Critical for Understanding Agent Behavior)

File	Lines	Responsibility
`openhands/llm/fn_call_converter.py`	979	Converts between native and text-based function calling formats
`openhands/llm/retry_mixin.py`	108	Tenacity-based retry with exponential backoff, temperature perturbation
`openhands/llm/metrics.py`	284	Cost, token, and latency tracking
`openhands/llm/model_features.py`	173	Pattern-based feature detection (function calling, caching, vision) per model
`openhands/agenthub/codeact_agent/function_calling.py`	345	Converts LLM responses to Action objects (CmdRun, FileEdit, etc.)
`openhands/core/message.py`	~200	Message serialization with dual strategy (list vs string)

Tier 3: System Prompts & Tools

File	Lines	Responsibility
`openhands/agenthub/codeact_agent/prompts/system_prompt.j2`	114	Core system prompt: role, guidelines, workflow
`openhands/agenthub/codeact_agent/prompts/security_risk_assessment.j2`	24	Security risk level definitions (CLI vs sandbox)
`openhands/agenthub/codeact_agent/prompts/system_prompt_interactive.j2`	14	Interactive mode additions
`openhands/agenthub/codeact_agent/prompts/system_prompt_long_horizon.j2`	46	Task tracking for complex workflows
`openhands/agenthub/codeact_agent/prompts/system_prompt_tech_philosophy.j2`	122	Linus Torvalds-inspired engineering philosophy
`openhands/agenthub/codeact_agent/prompts/additional_info.j2`	53	Repository/runtime context injection
`openhands/agenthub/codeact_agent/prompts/in_context_learning_example.j2`	165	Full task execution example for non-native function calling
`openhands/agenthub/codeact_agent/tools/bash.py`	89	Bash tool definition with timeout, interactive mode
`openhands/agenthub/codeact_agent/tools/str_replace_editor.py`	168	File viewing/editing tool (view, create, str_replace, insert, undo)
`openhands/agenthub/codeact_agent/tools/browser.py`	178	Browser interaction tool (15 Playwright-like functions)
`openhands/agenthub/codeact_agent/tools/llm_based_edit.py`	162	LLM-based file editing with draft approach
`openhands/agenthub/codeact_agent/tools/think.py`	34	Internal reasoning tool
`openhands/agenthub/codeact_agent/tools/finish.py`	41	Task completion signaling
`openhands/agenthub/codeact_agent/tools/ipython.py`	41	Python execution in IPython
`openhands/agenthub/codeact_agent/tools/task_tracker.py`	210	Structured task management

Tier 4: Memory & Condensation

File	Lines	Responsibility
`openhands/memory/memory.py`	405	Memory manager: microagent loading, recall handling
`openhands/memory/conversation_memory.py`	~800	Event → Message conversion for LLM context
`openhands/memory/condenser/condenser.py`	~200	Condenser base class, rolling condenser, View/Condensation types
`openhands/memory/condenser/impl/llm_summarizing_condenser.py`	~180	LLM-generated summaries with task tracking preservation
`openhands/memory/condenser/impl/structured_summary_condenser.py`	~100	Structured field extraction for summaries
`openhands/memory/condenser/impl/observation_masking_condenser.py`	~30	Masks old observations with `<MASKED>`
`openhands/microagent/microagent.py`	~250	Microagent loading, types (Knowledge, Repo, Task), trigger matching

Tier 5: State Management

File	Lines	Responsibility
`openhands/controller/state/state.py`	~250	State class: session, history, iteration/budget flags, metrics
`openhands/controller/state/state_tracker.py`	~200	State persistence and history initialization from EventStream
`openhands/controller/state/control_flags.py`	103	Iteration and budget limit enforcement
`openhands/controller/stuck.py`	~200	Stuck detection: 5 loop types, analysis reporting
`openhands/core/schema/agent.py`	~50	AgentState enum definition

Tier 6: Runtime & Server

File	Lines	Responsibility
`openhands/runtime/impl/docker/docker_runtime.py`	~800	Docker container creation, port mapping, action execution
`openhands/runtime/action_execution_server.py`	~1000	FastAPI server inside sandbox: bash, files, browser, MCP
`openhands/server/app.py`	~105	V0 FastAPI app: routes, lifespan, middleware
`openhands/app_server/v1_router.py`	~38	V1 API router
`openhands/server/listen_socket.py`	~150	WebSocket/Socket.IO: connection, auth, event streaming
`openhands/server/conversation_manager/standalone_conversation_manager.py`	~900	Session lifecycle management
`openhands/server/session/agent_session.py`	~500	Agent session: runtime + controller + memory lifecycle

Tier 7: Configuration

File	Lines	Responsibility
`openhands/core/config/openhands_config.py`	~300	Main config: LLM, agents, sandbox, storage, MCP, git
`openhands/core/config/llm_config.py`	205	LLM config: model, API key, retry, caching, vision, function calling
`openhands/core/config/sandbox_config.py`	133	Sandbox config: image, timeout, GPU, volumes, network
`openhands/core/config/mcp_config.py`	173	MCP server config: HTTP/SSE, Stdio, default servers
`config.template.toml`	~50	User-facing config template

Tier 8: Events (Actions & Observations)

File	Lines	Responsibility
`openhands/events/action/agent.py`	~200	Agent actions: Finish, Think, Delegate, Recall, Condensation
`openhands/events/action/commands.py`	~80	CmdRunAction, IPythonRunCellAction
`openhands/events/action/files.py`	~100	FileRead, FileWrite, FileEdit actions
`openhands/events/action/message.py`	~50	MessageAction, SystemMessageAction
`openhands/events/action/browse.py`	~60	BrowseURL, BrowseInteractive actions
`openhands/events/action/mcp.py`	~30	MCPAction for MCP tool calls
`openhands/events/observation/agent.py`	139	RecallObservation with MicroagentKnowledge
`openhands/events/observation/commands.py`	~60	CmdOutput, IPythonRunCell observations
`openhands/events/observation/error.py`	~30	ErrorObservation
`openhands/events/observation/loop_recovery.py`	~40	LoopDetectionObservation

Tier 9: Skills & Microagents

File	Lines	Responsibility
`skills/README.md`	161	Skills system documentation
`skills/github.md`	36	GitHub operations knowledge
`skills/code-review.md`	58	Code review persona
`skills/fix_test.md`	24	Test fixing workflow
`skills/agent-builder.md`	40	Custom agent building
`skills/default-tools.md`	15	Default MCP tool config

Tier 10: Security

File	Lines	Responsibility
`openhands/security/analyzer.py`	45	Abstract SecurityAnalyzer interface
`openhands/security/llm/analyzer.py`	~50	LLM-assessed risk level reader
`openhands/security/invariant/analyzer.py`	~150	Policy-based security analysis
`openhands/security/invariant/policies.py`	~100	Security policy definitions

Tier 11: Integrations

File	Lines	Responsibility
`openhands/integrations/provider.py`	~350	Multi-provider handler: GitHub, GitLab, Bitbucket, Azure DevOps, Forgejo
`openhands/mcp/client.py`	178	MCP client: HTTP/SSE and Stdio transport, tool discovery
`openhands/resolver/`	~500+	GitHub issue resolver (headless agent for automated issue fixing)

File Dependency Map

                    openhands_config.py
                    ├── llm_config.py
                    ├── sandbox_config.py
                    ├── agent_config.py
                    └── mcp_config.py
                          │
                          v
                    agent_session.py
                    ├── agent_controller.py
                    │   ├── agent.py (abstract)
                    │   │   └── codeact_agent.py
                    │   │       ├── prompts/*.j2
                    │   │       ├── tools/*.py
                    │   │       ├── function_calling.py
                    │   │       └── conversation_memory.py
                    │   │           └── condenser/
                    │   ├── state.py
                    │   │   ├── state_tracker.py
                    │   │   └── control_flags.py
                    │   ├── stuck.py
                    │   └── replay.py
                    │
                    ├── event_stream.py
                    │   ├── event.py
                    │   ├── action/*.py
                    │   └── observation/*.py
                    │
                    ├── memory.py
                    │   └── microagent.py
                    │       └── skills/*.md
                    │
                    ├── runtime (Docker/K8s/Local)
                    │   └── action_execution_server.py
                    │
                    ├── llm.py
                    │   ├── retry_mixin.py
                    │   ├── debug_mixin.py
                    │   ├── metrics.py
                    │   ├── model_features.py
                    │   ├── fn_call_converter.py
                    │   └── llm_registry.py
                    │
                    └── security/analyzer.py

Important Prompt Files

These Jinja2 templates define how the LLM behaves. They are the "soul" of the agent:

Template	Key Sections	Impact
`system_prompt.j2`	ROLE, EFFICIENCY, FILE_SYSTEM_GUIDELINES, CODE_QUALITY, VERSION_CONTROL, PROBLEM_SOLVING_WORKFLOW, SECURITY, PROCESS_MANAGEMENT	Defines all baseline agent behavior
`security_risk_assessment.j2`	LOW/MEDIUM/HIGH definitions	Determines how agent classifies action risk
`additional_info.j2`	REPOSITORY_INFO, RUNTIME_INFORMATION	Provides workspace context to agent
`in_context_learning_example.j2`	Full task walkthrough	Teaches non-native function calling format
`system_prompt_long_horizon.j2`	TASK_MANAGEMENT, TASK_TRACKING_PERSISTENCE	Enables structured multi-step workflows
`system_prompt_tech_philosophy.j2`	4 core principles, 5-layer problem decomposition	Alternative engineering philosophy mode