tunacode-cli 0.1.4__tar.gz → 0.1.28__tar.gz

tunacode_cli-0.1.28/.claude/JOURNAL.md

@@ -0,0 +1,278 @@
+# Claude Journal
+
+## 2026-01-07: Renderer Unification
+
+Unifying the 8 tool renderers in `src/tunacode/ui/renderers/tools/` to eliminate duplication via a shared base class and registry pattern.
+
+### Completed:
+- Created `base.py` with `BaseToolRenderer[T]` ABC and `ToolRendererProtocol`
+- Extracted shared helpers: `truncate_line`, `truncate_content`, `pad_lines`
+- Added registry pattern: `@tool_renderer`, `get_renderer`, `list_renderers`
+- Migrated `list_dir.py` to use `BaseToolRenderer` (199 -> 149 lines)
+- Created documentation at `docs/ui/tool_renderers.md`
+
+### Architecture Decisions:
+- Module-level singleton renderer instances (not created per-call)
+- Render functions remain the public API (backward compatible)
+- `@tool_renderer` decorator for self-registration
+- Helpers are standalone functions, not methods
+
+---
+
+## 2026-01-07: Local Mode Context Optimization
+
+### Problem:
+- System prompt + tool schemas used ~3.5k tokens before any conversation
+- Each file read could use 2000 lines (~20k tokens)
+- With 10k context, only ~6.5k left for conversation
+- LLM APIs are stateless - system prompt sent every turn
+
+### Solution:
+
+**1. Minimal System Prompt**
+- `LOCAL_TEMPLATE` in `templates.py` - only 3 sections: AGENT_ROLE, TOOL_USE, USER_INSTRUCTIONS
+- `local_mode: true` setting triggers minimal template
+
+**2. Minimal Tool Schemas**
+- Reduced from 11 tools to 6 (bash, read_file, update_file, write_file, glob, list_dir)
+- 1-word descriptions ("Shell", "Read", "Edit", etc.) - saves ~1k tokens
+
+**3. Aggressive Pruning**
+- LOCAL_PRUNE_PROTECT_TOKENS: 2,000 (vs 40,000)
+- LOCAL_PRUNE_MINIMUM_THRESHOLD: 500 (vs 20,000)
+
+**4. Tool Output Limits**
+- LOCAL_DEFAULT_READ_LIMIT: 200 lines (vs 2,000)
+- LOCAL_MAX_LINE_LENGTH: 500 chars (vs 2,000)
+- LOCAL_MAX_COMMAND_OUTPUT: 1,500 chars (vs 5,000)
+
+**5. Response Limit**
+- local_max_tokens: 1000 - caps model output per turn
+
+### Token Budget (Local Mode):
+| Component | Tokens |
+|-----------|--------|
+| System prompt | ~1,100 |
+| Guide file | ~500 |
+| 6 tools (minimal) | ~575 |
+| **Total base** | **~2,200** |
+
+With 10k context: ~7.8k available for conversation.
+
+### Key Insight:
+LLM APIs are stateless. Every request sends: system prompt + tool schemas + full conversation history. Model has no memory - re-reads everything each turn.
+
+### Key Files:
+- `src/tunacode/core/limits.py` - Centralized limit configuration
+- `src/tunacode/core/prompting/templates.py` - LOCAL_TEMPLATE
+- `src/tunacode/core/prompting/local_prompt.md` - Condensed prompt
+- `src/tunacode/core/compaction.py` - Dynamic prune thresholds
+- `src/tunacode/constants.py` - Local mode limit constants
+
+---
+
+## 2026-01-06: Local Model Support
+
+### Task: Add local model support to tunacode
+
+### Completed:
+- Created condensed system prompt at `src/tunacode/prompts/local_model_prompt.txt` (~500 bytes vs 34KB full prompt)
+- Added `local_model: true/false` setting in config defaults
+- Modified `load_system_prompt()` to use condensed prompt when `local_model=true`
+- Added cache invalidation for `local_model` setting in `_compute_agent_version()`
+- Skip AGENTS.md loading for local models to save tokens
+- Created `fallback_executor.py` for models that output tool calls in text (e.g., `<tool_call>` tags)
+- Updated `node_processor.py` to detect and execute fallback tool calls
+- Passed `agent_ctx` through the call chain for result injection
+- Tested with multiple local models via LM Studio/vLLM
+
+### Notes:
+- Qwen2.5-Coder-14B supports native OpenAI tool calling format
+- Smaller models (0.6B-1.7B) output `<tool_call>` tags in content - fallback parser handles this
+- llama.cpp uses KV cache efficiently (LCP similarity) so repeated prompt not re-computed
+
+---
+
+## 2026-01-08: Config Restoration & Local Mode Docs
+
+### Task: Restore pre-local-mode config and document local mode setup
+
+### Completed:
+
+**1. Config Backup Discovery**
+Found three config variants in `~/.config/`:
+- `tunacode.json` - was set to local mode (grok-code-fast-1, 10k context)
+- `tunacode.json.bak` - MiniMax-M2.1, 200k context, no local mode
+- `@tunacode.json` - Gemini 3 Pro via OpenRouter
+
+**2. Restored Config**
+- Restored `~/.config/tunacode.json` from `.bak` (MiniMax config)
+- Settings: `minimax:MiniMax-M2.1`, 200k context, `guide_file: AGENTS.md`
+
+**3. Created Local Mode Example**
+- Created `docs/configuration/tunacode.local.json.example`
+- Documents all local mode settings:
+  - `local_mode: true`
+  - `local_max_tokens: 1000`
+  - `context_window_size: 10000`
+  - `OPENAI_BASE_URL: http://127.0.0.1:8080/v1`
+  - `guide_file: CLAUDE_LOCAL.md`
+
+### Key Files:
+- `~/.config/tunacode.json` - user config (restored to MiniMax)
+- `docs/configuration/tunacode.json.example` - standard example
+- `docs/configuration/tunacode.local.json.example` - NEW: local mode example
+
+### Notes:
+- Local mode uses condensed prompts and minimal tool schemas for small context windows
+- The `.bak` file preserved the pre-experimentation state - good backup hygiene!
+- User was testing local models, now back to cloud (MiniMax)
+
+---
+
+## 2026-01-08: Syntax Highlighting for Tool Renderers (Branch: ui-model-work)
+
+### The Mission:
+Make tool outputs pretty! All those ugly plain text viewports were a crime against NeXTSTEP aesthetics. Time to add syntax highlighting everywhere.
+
+### Completed (Commit 9db8e92):
+
+**1. Created `syntax_utils.py` - The Shared Foundation**
+- `EXTENSION_LEXERS` - 60+ file extension → lexer mappings
+- `get_lexer(filepath)` - Get pygments lexer from file path
+- `syntax_or_text(content, filepath)` - Render highlighted or plain
+- `detect_code_lexer(content)` - Heuristic code detection (shebangs, JSON, Python/JS patterns)
+- `SYNTAX_THEME = "monokai"` - Consistent theme everywhere
+
+**2. Created `write_file.py` - New Renderer!**
+- Was missing entirely - now shows syntax-highlighted preview of written content
+- Green "NEW" badge in header, file stats
+
+**3. Updated 8 Existing Renderers:**
+
+| Renderer | What Changed |
+|----------|-------------|
+| `read_file` | Syntax highlighting by file extension, built-in line numbers from Syntax component |
+| `grep` | Cyan file paths, yellow `reverse` highlighted matches, styled line numbers with `│` |
+| `glob` | Files colored by type: Python=bright_blue, JS=yellow, JSON=green, etc. Dir path dim, filename bold |
+| `list_dir` | Tree chars dim, directories bold cyan, files colored by lexer type |
+| `bash` | Smart detection: `git diff`→diff lexer, JSON commands→json lexer, labeled stdout/stderr |
+| `web_fetch` | URL-based detection (raw.githubusercontent.com, .json, /api/), content heuristics |
+| `research` | New "Code" section with syntax-highlighted examples from `code_examples` field |
+| `update_file` | Already had Syntax("diff") - unchanged, the OG |
+
+**4. Updated `__init__.py`:**
+- Added `write_file` renderer to exports
+- Added syntax utility functions to `__all__`
+- Better docstring explaining the 4-zone pattern
+
+### Key Design Decisions:
+- `syntax_or_text()` returns `RenderableType` - graceful fallback to `Text()` for unknown extensions
+- File-type coloring consistent across `glob`, `list_dir`, `grep` (same color = same type)
+- Bash output detection is conservative - only highlights when confident
+- Research viewport prioritizes findings over code (code is supplementary)
+
+### Files Modified:
+```
+src/tunacode/ui/renderers/tools/
+├── __init__.py        (exports + docstring)
+├── syntax_utils.py    (NEW - shared utilities)
+├── write_file.py      (NEW - renderer)
+├── read_file.py       (syntax highlighting)
+├── grep.py            (styled matches)
+├── glob.py            (colored paths)
+├── list_dir.py        (styled tree)
+├── bash.py            (smart detection)
+├── web_fetch.py       (URL/content detection)
+└── research.py        (code examples)
+```
+
+### What's Left on This Branch:
+- Other UI model work (the branch name suggests more to do)
+- Unstaged: `.claude/JOURNAL.md`, `CLAUDE.md`, research docs, config example
+
+### Commands:
+```bash
+uv run ruff check src/tunacode/ui/renderers/tools/  # All checks pass
+uv run python -c "from tunacode.ui.renderers.tools import list_renderers; print(list_renderers())"
+# ['bash', 'glob', 'grep', 'list_dir', 'read_file', 'research_codebase', 'update_file', 'web_fetch', 'write_file']
+```
+
+### Fun Fact:
+We went from 0 syntax-highlighted viewports to 8 in one session. The `update_file` renderer was the lonely pioneer - now it has friends!
+
+---
+
+## 2026-01-08: The Great Panel Width Debugging Adventure (Branch: master)
+
+### The Problem:
+Tool panels were narrower than agent panels. User showed screenshot - `read_file` panel was ~50 chars wide while `agent` panel was full width. Classic NeXTSTEP violation!
+
+### The Red Herring (What We Thought):
+Initially believed the issue was `width=TOOL_PANEL_WIDTH` (50 chars) on `Panel()` calls. Spent time:
+- Removing `width=TOOL_PANEL_WIDTH` from 7 Panel() calls in `panels.py`
+- Removing it from `search.py`, `update_file.py`, `app.py`
+- Cleaning up unused imports
+
+But panels were STILL narrow after restart. User called me out: "stop being lazy, dig deeper"
+
+### The Actual Root Cause (The AHA Moment):
+
+**Textual's `RichLog.write()` has its OWN `expand` parameter that defaults to `False`!**
+
+From `.venv/lib/python3.13/site-packages/textual/widgets/_rich_log.py`:
+```python
+def write(
+    self,
+    content: RenderableType | object,
+    width: int | None = None,
+    expand: bool = False,  # <-- THIS IS THE VILLAIN
+    shrink: bool = True,
+    ...
+)
+```
+
+When `expand=False` (default), RichLog measures the content's minimum width and renders at that width, **completely ignoring** the Panel's own `expand=True` property!
+
+The Panel's expand tells Rich "expand to console width", but RichLog overrides the console width to be just the measured content width. Two different expand flags, two different systems!
+
+### The Real Fix:
+Pass `expand=True` to `rich_log.write()`:
+
+```python
+# Before
+self.rich_log.write(panel)
+
+# After
+self.rich_log.write(panel, expand=True)
+```
+
+### Files Modified:
+| File | Change |
+|------|--------|
+| `src/tunacode/ui/app.py` | 3 panel writes → `expand=True` (lines 325, 377, 558) |
+| `src/tunacode/ui/plan_approval.py` | 1 panel write → `expand=True` (line 132) |
+| `src/tunacode/ui/renderers/panels.py` | Removed `width=TOOL_PANEL_WIDTH` (harmless cleanup) |
+| `src/tunacode/ui/renderers/search.py` | Removed unused import |
+| `src/tunacode/ui/renderers/tools/update_file.py` | Removed unused import |
+
+### The Lesson:
+When Rich Panel has `expand=True` but isn't expanding in Textual:
+1. The Panel's expand is **not** the issue
+2. Check how the panel is being **written** to the widget
+3. RichLog.write() has its own expand parameter!
+
+### Status:
+- Changes made, ruff passes
+- NOT COMMITTED YET - user needs to test
+- Previous width removal changes are technically unnecessary but harmless
+
+### Commands:
+```bash
+git diff --stat  # See all changes
+uv run ruff check src/tunacode/ui/  # Verify
+# Restart tunacode and make NEW request to test
+```
+
+### Philosophical Note:
+This bug was a perfect example of "the abstraction leaked". Panel.expand and RichLog.write(expand=) look like they should be the same thing, but they operate at different levels. Panel tells Rich what to do. RichLog tells Rich what size canvas to give it. The canvas size wins.

tunacode_cli-0.1.28/.claude/debug_history/list-dir-tool-execution-error.md

@@ -0,0 +1,55 @@
+---
+title: list_dir halts agent on bad paths
+link: list-dir-tool-execution-error
+type: delta
+path: src/tunacode/tools/list_dir.py
+depth: 0
+seams: [M] module
+ontological_relations:
+  - relates_to: [[tools]]
+  - affects: [[tool-executor]]
+  - fixes: [[agent-halt-on-tool-error]]
+tags:
+  - tools
+  - error-handling
+  - list_dir
+  - ModelRetry
+created_at: 2026-01-07T22:54:00-08:00
+updated_at: 2026-01-07T23:15:00-08:00
+uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+---
+
+## Summary
+
+`list_dir` raised `FileNotFoundError` on non-existent directories, which `@base_tool` wrapped as `ToolExecutionError`. Since `ToolExecutionError` is in `NON_RETRYABLE_ERRORS`, the agent halted instead of letting the LLM self-correct with a valid path.
+
+## Context
+
+Surfaced when agent called `list_dir("/home/tuna/tunacode/apps")` - a directory that doesn't exist. Agent crashed with `ToolExecutionError` instead of retrying.
+
+## Root Cause
+
+Error propagation chain:
+1. `list_dir` raises `FileNotFoundError`
+2. `@base_tool` decorator wraps it as `ToolExecutionError`
+3. `tool_executor.py` has `ToolExecutionError` in `NON_RETRYABLE_ERRORS`
+4. Non-retryable errors propagate immediately, halting the agent
+
+First attempted fix: switch to `@file_tool` decorator. Failed because `@file_tool` expects required `filepath` positional arg, but `list_dir` has optional `directory="."`.
+
+## Changes
+
+- Import `ModelRetry` from `pydantic_ai.exceptions`
+- Replace `raise FileNotFoundError(...)` with `raise ModelRetry(...)`
+- Replace `raise NotADirectoryError(...)` with `raise ModelRetry(...)`
+- Keep `@base_tool` decorator (not `@file_tool`)
+
+## Behavioral Impact
+
+- Agent no longer halts on bad directory paths
+- LLM receives retry signal with error message, can self-correct
+- No change to valid path behavior
+
+## Related Cards
+
+- [[glob-grep-error-strings]] - similar smell: return error strings instead of raising

tunacode_cli-0.1.28/.claude/qa/no-cargo-cult-fixes.md

@@ -0,0 +1,52 @@
+---
+title: No Cargo Cult Fixes - Question Every Change
+link: no-cargo-cult-fixes
+type: qa
+path: qa/
+depth: 1
+seams: [M]
+ontological_relations:
+  - relates_to: [[code-review]]
+  - affects: [[all-modules]]
+  - fixes: [[scope-creep]]
+tags:
+  - discipline
+  - shims
+  - code-review
+created_at: 2026-01-09T22:15:00Z
+updated_at: 2026-01-09T22:15:00Z
+uuid: 4fa0c1e7-d7d0-415a-91e4-d69b28210ff0
+---
+
+## Problem
+
+When extracting changes from a messy PR, I blindly copied a fix to `retry.py` without questioning whether it was needed.
+
+The signature preservation fix was for pydantic-ai tool schema generation. `retry_on_json_error` is a JSON parsing utility - it never gets passed to pydantic-ai's `Tool()`. The fix there was a shim.
+
+## Root Cause
+
+Cargo culting. "The original PR had it, so I included it."
+
+## Lesson
+
+Before applying any fix, ask: **"Does this code path actually hit the problem?"**
+
+For the signature preservation bug specifically:
+- pydantic-ai uses `inspect.signature()` to generate JSON schemas for tools
+- Only wrappers that produce functions passed to `Tool()` need the fix
+- `retry_on_json_error` wraps JSON parsers, not pydantic-ai tools
+
+## Rule
+
+If you encounter a shim, fix it. Don't care who made it. Don't propagate it.
+
+## Files That Actually Needed The Fix
+
+1. `research_agent.py` - `ProgressTracker.wrap_tool()` wraps tools for pydantic-ai
+2. `decorators.py` - `base_tool()` and `file_tool()` wrap tools for pydantic-ai
+3. `present_plan.py` - `create_present_plan_tool()` creates a pydantic-ai tool
+
+## Files That Did NOT Need The Fix
+
+- `retry.py` - wraps JSON parsers, not pydantic-ai tools

{tunacode_cli-0.1.4 → tunacode_cli-0.1.28}/.github/pull_request_template.md

@@ -13,7 +13,7 @@
 
 ## Testing
 <!-- Describe the tests you ran to verify your changes -->
-- [ ] All existing tests pass (`hatch run test`)
+- [ ] All existing tests pass (`uv run pytest`)
 - [ ] New tests have been added to cover the changes
 - [ ] Tests have been run locally
 - [ ] Golden/character tests established for new features

tunacode_cli-0.1.28/.github/workflows/lint.yml

@@ -0,0 +1,20 @@
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v4
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files

{tunacode_cli-0.1.4 → tunacode_cli-0.1.28}/.github/workflows/publish-release.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install build tooling
         run: |
           python -m pip install --upgrade pip
-          pip install hatch twine uv ruff pytest pytest-cov pytest-asyncio
+          pip install build twine ruff pytest pytest-cov pytest-asyncio
 
       - name: Install project dependencies
         run: pip install -e '.[dev]'
@@ -63,7 +63,7 @@ jobs:
           fi
 
       - name: Build
-        run: hatch build
+        run: python -m build
 
       # Preferred: API token secret
       - name: Publish to PyPI (API token)

{tunacode_cli-0.1.4 → tunacode_cli-0.1.28}/.gitignore

@@ -32,7 +32,6 @@ venv/
 ENV/
 .env
 .deploy_venv/
-uv.lock
 
 # IDE files
 .idea/
@@ -80,3 +79,7 @@ node_modules/
 # Task files
 vendor/
 .beads/
+.osgrep
+.osgrep*
+.pre-commit-cache/
+TODO.md

{tunacode_cli-0.1.4 → tunacode_cli-0.1.28}/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ default_language_version:
   python: python3
 
 # Global exclusions to prevent hooks from scanning unnecessary directories
-exclude: ^(venv/|build/|dist/|\.git/|__pycache__/|.*\.egg-info/|\.pytest_cache/|\.mypy_cache/|\.ruff_cache/|htmlcov/|\.coverage|reports/|llm-agent-tools/)
+exclude: ^(venv/|build/|dist/|\.git/|__pycache__/|.*\.egg-info/|\.pytest_cache/|\.mypy_cache/|\.ruff_cache/|\.uv-cache/|\.uv_cache/|htmlcov/|\.coverage|reports/|llm-agent-tools/)
 
 repos:
   # Pre-commit framework hooks
@@ -13,6 +13,9 @@ repos:
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
+        # models_registry.json is auto-generated config; lsp/__init__.py is empty stub
+        # trailing newline changes create diff noise
+        exclude: (models_registry\.json|lsp/__init__\.py)$
       - id: check-yaml
         args: ['--allow-multiple-documents']
       - id: check-added-large-files
@@ -39,11 +42,12 @@ repos:
 
   # Ruff - Fast Python linter and formatter
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.6
+    rev: v0.14.9
     hooks:
       - id: ruff
         args: ['--fix', '--show-fixes']
-      # - id: ruff-format  # Disabled - hatch-lint already handles formatting
+      - id: ruff-format  # Re-enabled - ruff handles linting, ruff-format handles formatting
+        exclude: (models_registry\.json|lsp/__init__\.py)$
 
   # Type checking with mypy
   - repo: https://github.com/pre-commit/mirrors-mypy
@@ -59,20 +63,9 @@ repos:
 
 
   # Local hooks for project-specific checks
-  # Strategy: Use 'hatch run' for commands defined in pyproject.toml scripts
-  #          Use 'uv run' for standalone tools not managed by hatch environments
   - repo: local
     hooks:
-      # Hatch-managed commands (use hatch run for consistency)
-      - id: hatch-lint
-        name: Run hatch lint check
-        entry: hatch run lint
-        language: system
-        pass_filenames: false
-        always_run: true
-        stages: [pre-commit]
-
-      # UV-managed standalone tools (not in hatch environments)
+      # UV-managed tools
       - id: dead-imports
         name: Check for unused imports in changed files
         entry: scripts/run-dead-imports.sh
@@ -144,5 +137,5 @@ ci:
   autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
   autoupdate_schedule: weekly
   # Skip hooks that require project-specific environment setup
-  skip: [hatch-lint, dead-imports, vulture-changed]
+  skip: [vulture-changed]
   submodules: false