Agent Mode Guide
Everything about the Thumper-Run AI agent: tools, templates, configuration, and best practices.
Overview
The agent uses the ReAct (Reason + Act) framework to solve tasks step by step:
- Your message enters the conversation
- The LLM reasons about what to do (Thought:)
- It selects a tool and provides JSON arguments (Action: + Action Input:)
- Permission check — safe tools auto-run, others need approval
- Tool executes with a timeout
- Result returned as Observation — loop repeats or agent gives Final Answer
Fully local by default. Conversations never leave your device unless you choose a cloud API backend.
All 32 Tools
Filesystem Tools (8)
| Tool | Safety | Timeout | Key Parameters |
|---|---|---|---|
| file_read | Safe | 10s | path, offset, limit |
| file_write | Confirm | 10s | path, content |
| file_edit | Confirm | 10s | path, old_string (exact match), new_string |
| list_files | Safe | 30s | path, recursive |
| search_files | Safe | 30s | pattern, path |
| search_code | Safe | 30s | pattern, path, regex |
| run_command | Confirm | 60s | command, working_dir |
| web_search | Safe | 30s | query |
Launcher Tools (6)
| Tool | Safety | Timeout | Key Parameters |
|---|---|---|---|
| list_apps | Safe | 10s | query, tag, runtime |
| app_status | Safe | varies | app_id |
| install_app | Confirm | 300s | source_url (git URL), app_id, branch |
| launch_app | Confirm | 120s | app_id, port (1024-65535), env |
| stop_app | Confirm | 60s | app_id, force (SIGKILL vs SIGTERM), timeout_secs |
| app_logs | Safe | 30s | app_id, lines, offset, level, search |
GPU & Manifest Diagnostic Tools (7)
| Tool | Safety | Timeout | Description |
|---|---|---|---|
| gpu_diagnose | Safe | 30s | Detect GPU vendor, model, VRAM, driver version |
| gpu_test_pytorch | Safe | 60s | Test torch.cuda / torch.hip availability in app venv |
| manifest_validate | Safe | 10s | Validate .thumper.yaml against schema |
| manifest_generate | Safe | 30s | Generate manifest from repo structure |
| manifest_fix | Safe | 30s | Auto-fix common manifest issues |
| install_debug | Safe | 60s | Debug installation failures (venv, deps, paths) |
| model_manage | Safe | 30s | Model file management (list, verify, info) |
Model Intelligence Tools (5)
| Tool | Safety | Timeout | Description |
|---|---|---|---|
| model_list | Safe | 30s | List models by location, filter, with stats |
| model_info | Safe | 10s | Get detailed info about a specific model |
| model_download | Confirm | 300s | Download from HF repo (repo_id, filename, revision) |
| workflow_analyze | Safe | 30s | Parse ComfyUI workflow, detect 17+ loader node types |
| hardware_status | Safe | 10s | VRAM, RAM, disk space, CPU info |
Model Manifest v2 Tools (3)
| Tool | Safety | Timeout | Description |
|---|---|---|---|
| model_manifest_validate | Safe | 10s | Validate .model.yaml/.pack.yaml against v2 schema |
| model_manifest_generate | Safe | 30s | Generate manifest from HF repo ID or local file |
| model_cache_diagnose | Safe | 30s | Disk usage, entry counts, duplicate detection |
Log & Diagnostic Tools (3)
| Tool | Safety | Timeout | Description |
|---|---|---|---|
| crash_log_debug | Safe | 30s | Analyze crash logs for root cause patterns |
| app_manifest_debug | Safe | 10s | Validate manifest fields and cross-references |
| app_diagnose | Safe | 60s | Composite: process + crashes + manifest + logs |
You don't need to memorize tool names. Describe what you want and the agent picks the right tools.
Templates
| Template | System Prompt Addition | Best For |
|---|---|---|
| (default) | Platform knowledge + all tools | App management, debugging, exploration |
| code-helper | "Focus on code-related tasks. Prefer search_code, file_read, file_edit. Show code snippets." | Editing configs, writing scripts, vibe coding |
| research-agent | "Focus on research. Use search_files, search_code, file_read. Summarize with bullet points." | Exploring codebases, reading logs, comparing files |
Your last-used template is persisted via CRDT at /user/agents/launch_preferences.
Model Selection
| Backend | Protocol | Setup | Offline | Cost |
|---|---|---|---|---|
| LlamaCpp | Native C++ FFI | Load .gguf from disk | Yes | Free |
| Ollama | REST localhost:11434 | Auto-managed by Thumper | Yes | Free |
| OpenAI Compatible | REST API | API key + endpoint URL | No | Per token |
| Anthropic | REST API | API key | No | Per token |
| Docker vLLM | REST to container | Docker setup | Yes | Free |
Recommended Models by Task
| Task | Model | Size | Why |
|---|---|---|---|
| Quick edits, YAML/JSON | qwen3:4b | 2.4 GB | Fast, low VRAM, good for structured data |
| Python code, debugging | codellama:7b | 4 GB | Code-specialized, good reasoning |
| General tasks | llama3.1:8b | 4.7 GB | Balanced speed and quality |
| Complex multi-file | llama3.1:70b | 40 GB | Highest quality reasoning |
Model selection is persisted via CRDT at /user/agents/launch_preferences.
Context & Memory
The agent uses a sliding window memory with these defaults:
- Max context messages: 50
- Summary threshold: 30 messages (triggers summarization)
- Keep recent: 6 messages (always preserved)
- Context size: 4096 tokens
- Output reserved: 1024 tokens
Compaction
At 90 messages, you'll see a compaction warning. At 128, the conversation auto-compacts — older messages are summarized to free space. A "Roll Back" button appears if you want to undo compaction.
File Attachments
At launch, you can attach files to give the agent initial context: image/*, .pdf, .txt, .md, .json, .csv.
External Knowledge File
Create ~/.local/share/tr-desktop/agent_knowledge.md (max ~2000 chars) to inject persistent context into every session. Loaded at priority 3.
Long tool outputs consume context fast. Use file_read with offset/limit for large files. A 1000-line file read uses ~3000 tokens of your 4096 budget.
Approval Workflow
Three Safety Tiers
| Level | Count | Behavior | Tools |
|---|---|---|---|
| Safe | 25 | Auto-run, no approval | All read-only and diagnostic tools |
| Confirm | 7 | Permission modal before execution | install_app, launch_app, stop_app, file_write, file_edit, run_command, model_download |
| Dangerous | - | Extra caution flagged | run_command with rm, kill, chmod |
Permission Modal
The modal shows: tool name, full arguments as JSON, risk description, and Approve/Deny buttons.
What Happens on Denial
The agent sees "User denied execution" as a ToolResult. It continues reasoning and may try an alternative approach or ask for guidance.
What to Check
| Tool | Verify |
|---|---|
| file_write / file_edit | File path and content changes |
| run_command | Full command — watch for rm, kill, curl to unknown URLs, pip install from untrusted sources |
| install_app | source_url (is it a trusted repo?) and branch |
| launch_app / stop_app | app_id, port, env variables, force flag |
| model_download | repo_id, disk space available |
Error Recovery
When a tool fails, the agent sees the error and can retry with different parameters. The executor has step_with_retry for malformed output. Per-tool timeouts: file ops=10s, search=30s, run_command=60s, install_app=300s.
Never approve run_command without reading it. Watch for: rm, kill, chmod, curl to unknown URLs, pip install from untrusted sources.
Session Management
Sessions are stored in two CRDT documents:
- Device (
/device/agents/running/{session_id}) — local only: session_id, status, current_task, is_paused, last_activity - User (
/user/agents/sessions/{session_id}) — user-scoped session state; current sync is server-assisted
Session status flow: Initializing → Ready → Thinking → Paused → Completed/Error
Maximum 10 concurrent sessions. IPC commands: agent_new_session, agent_get_history, agent_list_tools.
Supported sessions can sync across paired devices through the current server-assisted CRDT path. Private E2EE remains planned.
Privacy & Boundaries
What the Agent Can Access
Files within ~/.local/share/tr-desktop/ (apps directory, models directory, agent_knowledge.md). The ToolContext has sandboxed: true and working_directory scoped to the project root.
What Leaves Your Device
Nothing with Ollama, LlamaCpp, or Docker vLLM. With cloud API backends (OpenAI Compatible, Anthropic): conversation text is sent to the API provider. Tool results stay local.
What the Agent CAN'T Do
- Cannot install system packages (apt, brew, pacman)
- Cannot modify files outside app directories
- Cannot train or fine-tune models
- Cannot access network services beyond API calls
- Cannot execute arbitrary Python outside run_command
- Cannot manage multiple devices simultaneously
- Cannot access API keys or secrets stored in the system
- Cannot make purchases or financial transactions
The platform prompt tells the agent: "You are the AI assistant embedded in Thumper-Run." It knows about apps, launcher, model hub, and its tool set — nothing more.
Configuration
| Setting | Default | Range | Description |
|---|---|---|---|
| temperature | 0.7 | 0.0 - 2.0 | LLM creativity/randomness |
| max_iterations | 25 | 1 - 100 | Max ReAct loop iterations per request |
| tools_enabled | all | - | Tool whitelist (empty = all) |
| preferred_backend | Ollama | - | Default LLM backend |
| system_prompt | (built-in) | - | Custom system prompt override (priority 9) |
Tips & Anti-Patterns
Do
- Be specific about file paths — saves a search_files call (~200 tokens)
- Use
code-helpertemplate for editing tasks - Attach reference files at launch for context
- Ask "what would you change?" before "change it" — discuss before executing
- Use "search then edit" for bulk changes across files
- Read tool arguments before approving
- Check diff view for file edits
- Create
agent_knowledge.mdfor persistent project context
Don't (Anti-Patterns)
- Don't ask the agent to read entire large files — use offset/limit or ask for specific sections
- Don't chain 10 requests in one message — work step by step
- Don't approve
run_commandwithout reading the full command - Don't expect the agent to remember previous sessions — each starts fresh (but can restore)
- Don't use cloud APIs for sensitive code — use local Ollama/LlamaCpp instead