# TunaCode Modules Index

> This directory contains comprehensive documentation for all modules in the TunaCode codebase.

- Skill: `tools-only/tunacode-modules-index` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/tunacode-modules-index`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/tunacode-modules-index/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/tunacode-modules-index

---


# TunaCode Modules Index

This directory contains comprehensive documentation for all modules in the TunaCode codebase.

## Documentation Format

Each module file includes:
- **title** - Module name
- **path** - Relative path from src/
- **type** - file or directory
- **depth** - Depth from src/ root
- **description** - Purpose and responsibility
- **exports** - Main classes and functions
- **seams** - Modification (M) and Extension (D) points

## Module Organization

### Overview
- **[00-overview.md](./00-overview.md)** - Complete package structure and design principles

### Core Modules
- **[core-state.md](./core-state.md)** - Central session state management (StateManager, SessionState)
- **[core-agents.md](./core-agents.md)** - AI agent orchestration (process_request, RequestOrchestrator)
- **[core-prompting.md](./core-prompting.md)** - System prompt composition (PromptingEngine, SectionLoader)
- **[core-compaction.md](./core-compaction.md)** - Context window management (prune_old_tool_outputs)
- **[core-logging.md](./core-logging.md)** - Unified structured logging (LogManager, LogRecord, FileHandler)
- **[core-sanitize.md](./core-sanitize.md)** - Message history cleanup (run_cleanup_loop, remove_dangling_tool_calls)
- **[core-lsp-status.md](./core-lsp-status.md)** - UI-facing LSP status facade (get_lsp_status)
- **[core-configuration.md](./core-configuration.md)** - Configuration defaults and model registry facade
- **[core-constants.md](./core-constants.md)** - UI-facing constants and theme facade
- **[core-types.md](./core-types.md)** - UI-facing type exports
- **[core-messaging.md](./core-messaging.md)** - Core message content facade (get_content)
- **[core-user-configuration.md](./core-user-configuration.md)** - User config persistence facade
- **[core-system-paths.md](./core-system-paths.md)** - Session/update helpers facade
- **[core-formatting.md](./core-formatting.md)** - Formatting helpers facade
- **[core-file-filter.md](./core-file-filter.md)** - File autocomplete filter facade

### UI Module
- **[ui-overview.md](./ui-overview.md)** - Textual TUI interface (TextualReplApp, screens, renderers)

### Tools Module
- **[tools-overview.md](./tools-overview.md)** - Tool implementations and decorators (base_tool, file_tool)

### Supporting Modules
- **[configuration.md](./configuration.md)** - User settings and model registry (load_user_config, ModelRegistry)
- **[types.md](./types.md)** - Type definitions and protocols (UserConfig, MessageHistory, ToolCallback)
- **[utils.md](./utils.md)** - Shared utilities (estimate_tokens, estimate_message_tokens, parse_json)
- **[utils-limits.md](./utils-limits.md)** - Tool output limits with cascading defaults
- **[lsp.md](./lsp.md)** - Language Server Protocol client (LSPClient, get_diagnostics)
- **[prompts.md](./prompts.md)** - Modular prompt sections (agent_role.md, critical_rules.md)
- **[exceptions.md](./exceptions.md)** - Custom exception hierarchy (TunaCodeError, ToolExecutionError)
- **[constants.md](./constants.md)** - Global constants and UI text (UI_COLORS, TOOL_NAMES)

## Quick Reference

### By Responsibility

**Agent & AI:**
- core-agents.md
- core-prompting.md
- core-state.md
- core-sanitize.md

**Logging & Debugging:**
- core-logging.md

**User Interface:**
- ui-overview.md
- constants.md

**Tools:**
- tools-overview.md

**Configuration:**
- configuration.md

**Utilities:**
- types.md
- utils.md
- lsp.md

**Error Handling:**
- exceptions.md

### By Directory

```
src/tunacode/
├── core/
│   ├── agents/ → core-agents.md
│   │   └── resume/sanitize.py → core-sanitize.md
│   ├── logging/ → core-logging.md
│   ├── prompting/ → core-prompting.md
│   ├── state.py → core-state.md
│   ├── compaction.py → core-compaction.md
│   ├── lsp_status.py → core-lsp-status.md
│   ├── configuration.py → core-configuration.md
│   ├── constants.py → core-constants.md
│   ├── types.py → core-types.md
│   ├── messaging.py → core-messaging.md
│   ├── user_configuration.py → core-user-configuration.md
│   ├── system_paths.py → core-system-paths.md
│   ├── formatting.py → core-formatting.md
│   ├── file_filter.py → core-file-filter.md
├── ui/ → ui-overview.md
├── tools/ → tools-overview.md
├── configuration/ → configuration.md
├── types/ → types.md
├── utils/ → utils.md
│   └── limits.py → utils-limits.md
├── lsp/ → lsp.md
├── prompts/ → prompts.md
├── exceptions.py → exceptions.md
└── constants.py → constants.md
```

## Seams Legend

- **M (Modification)** - Points where you can modify existing behavior
- **D (Extension)** - Points where you can extend with new functionality

## Usage

1. **For Understanding:** Start with 00-overview.md, then dive into specific modules
2. **For Development:** Refer to specific module documentation before making changes
3. **For Onboarding:** Read overview, then core modules, then supporting modules

## Generated By

This documentation was generated using the Gemini MCP tool for code analysis.
- Analysis date: 2026-01-04
- Depth: 0 (top-level modules)
- Analyzer: Gemini 2.5 Flash