I am a garlic farmer from Korea. I want to share a personal smartphone-based AI agent
I developed over several intensive days. Without access to a PC, I built everything using
only my phone and sheer determination. All development was conducted in Korean.
This whitepaper was translated with the collaborative help of multiple AI assistants.
Demonstration Video
Below is the actual working video of Garlic Terminal in action:
Executive Summary
- Unihertz Titan2 Phone Termux-Based Autonomous Agent: Operates on Android (Termux) without a PC, > managing over 5,800 documents (108MB) as an AI agent ...
๐ง Garlic Terminal v2.0 Whitepaper
Korean Natural Language-Based Semi-Autonomous Android AI Agent โ RAG, GarlicLang, Multi-Provider Support
Executive Summary
- Unihertz Titan2 Phone Termux-Based Autonomous Agent: Operates on Android (Termux) without a PC, managing over 5,800 documents (108MB) as an AI agent
- GarlicLang (Custom Script Language): Eliminates token waste from automatic validation, local execution, and API ping-pong conversations through a sandboxed scripting language
- Hybrid RAG and Hallucination Prevention: Combines FTS5 full-text search with vector similarity search, and blocks AI hallucinations through verify_tool_response to ensure superior accuracy compared to existing AI chatbots
System Architecture
The Garlic Terminal operates through a multi-layered architecture. The browser UI communicates with web.py through Server-Sent Events (SSE), enabling real-time token and log streaming. The sidebar.js manages chat sessions and HUD display, while agent.py serves as the core orchestration engine. The search.py module handles RAG operations on knowledge.db, and garliclang_bridge.py executes GarlicLang scripts. Multi-provider LLM APIs (Cerebras, Gemini, DeepSeek) are accessed through the agent engine with automatic fallback capabilities.
Core Components
web.py (930 lines) & agent.html (1,218 lines)
A zero-dependency backend server based on Python's built-in http.server that serves as a bridge between the Termux environment and users. It streams AI tokens and tool execution logs in real-time through SSE (Server-Sent Events), and provides file writing and database reading endpoints wrapped in a split terminal UI.
agent.py (893 lines)
Serves as the agent's brain. It orchestrates the entire workflow, handles tool parsing (parse_tools), and strictly isolates Python/Bash execution to prevent destructive operations.
def run_agent(user_input, on_event=None, preferred_provider=None, no_fallback=False):
Core agent execution engine
pass
RAG Search Engine
Based on search.py (128 lines), it replaces standard SQL wildcards with a powerful hybrid system. It stores 5,879 documents in knowledge.db locally and combines FTS5 full-text search with cosine similarity vector matching to extract precise context. It automatically removes Korean particles (์/๋/์ด/๊ฐ, etc.) to improve keyword matching rates.
Security Model and Hallucination Prevention
The most important aspects of an autonomous agent are preventing infinite loops and blocking API cost spikes.
Hallucination Prevention (verify_tool_response): Compares AI claims against actual tool execution results, identifying hallucinations when there's a mismatch.
def verify_tool_response(tool_results, ai_response):
Compare AI-claimed results against actual tool output
pass
Local Delegation: The AI writes execution plans to .gl files and calls [tool:garlic] only once, reducing API usage by 80%.
Command Blocking: Hardcoded rules in web.py pre-block dangerous commands like rm -rf, direct sqlite3 access, and path access outside ~/garlic-agent/.
UI Features
Split Terminal: The interface displays AI conversation on the left and real-time execution logs and terminal output on the right simultaneously, allowing users to monitor both conversation flow and system operations.
Session Sidebar (sidebar.js, 138 lines): Provides chat session history management and conversation list selection UI, enabling users to switch between different conversation threads.
HUD (Heads-Up Display): Displays CPU, memory, disk, swap, llama status, web server status, and wake-lock status in real-time on the upper right corner of the screen, providing instant system health monitoring.
GarlicLang โ Autonomous Delegation Script Language
A Korean-based domain-specific language (DSL) created to solve the API "ping-pong" problem, allowing the agent to execute complex multi-step operations locally without repeated API calls.
Execution Details
Execution file: garliclang_bridge.py
Execution function: run_garliclang_source(source, context)
Syntax Examples
[execute] ls -la โ Executes bash commands through subprocess.run()
[output] Current time is {time} โ Outputs text with variable substitution support
[set_variable] count = 5 โ Stores internal variables
[condition] {count} > 3 โ Performs branching logic
[repeat] 3 โ Executes loops
[verify] file_exists ~/garlic-agent/web.py โ Returns PASS/FAIL verification results
System Statistics (v1.5.x)
Total code: approximately 3,506 lines
Knowledge base: 5,879 documents (108MB)
Chat history database: 52KB
Automated scripts: 137 .gl files
Supported providers: DeepSeek, Gemini (Flash/Pro), Cerebras, and others dynamically managed via config.json
Known Issues and Roadmap
Token Bleed: Past error logs accumulate in multi-turn context. This is mitigated by recommending new sessions after large-scale operations.
Provider Timeout: NVIDIA Kimi K2.5 frequently encounters 429 errors or timeouts (120-second limit).
Future Improvements: Implement VFS (Virtual File System) mirroring for complete pre-validation sandbox testing and enhanced security isolation.
Critical Incident Records and Absolute Rules
The system's core principles emerged from actual critical failures. Future AI agents must learn from these incidents to avoid repeating the same mistakes.
Incident 1: agent.html Backup Restoration Disaster (2026-02-25)
What Happened: When restoring agent.html, AI used archive/bak/*.bak instead of the full system backup (.tar.gz), resulting in loss of several hours of work.
Root Cause: Files in archive/bak/ are incremental backups taken immediately before individual modifications. When multiple edits accumulate, they cannot guarantee the latest state.
Absolute Rule: Always check ls /storage/emulated/0/Download/garlic-agent-.tar.gz first before restoring. Extract only the relevant file from the latest tar archive. Use archive/bak/.bak only as an absolute last resort.
Incident 2: python3 -c One-liner Permanently Banned
What Happened: Executing multi-line scripts with python3 -c caused line breaks to collapse and quote conflicts to occur, destroying system logic and failing silently.
Absolute Rule: Complex Python code must always be created as .py files and executed with python3 filename.py instead of inline commands.
Incident 3: Root Path (/) Access Violation
What Happened: AI hallucinated /garlic-agent/ instead of ~/garlic-agent/, resulting in 3 consecutive failures and massive token waste.
Absolute Rule: Strictly prohibit /garlic-agent/ usage and always use ~/garlic-agent/ for all operations.
Incident 4: Infinite Retry Causing API Overcharging
What Happened: Failed tool:patch commands were blindly retried without checking file status, resulting in massive unexpected API charges.
Absolute Rule: Stop immediately on 3 consecutive failures and report to the user. Always recommend starting a new session after large-scale operations.
Technical Specifications
Core Architecture
Runtime: Python 3.11+ (Android Termux optimized)
Agent Engine: Garlic Agent v1.5.x for autonomous tool calling and scenario execution
Validation Language: GarlicLang v20.x for multi-step verification and local interpretation
Monitoring System: watchdog.sh for 3-second interval process monitoring with automatic recovery
Data and Search Engine
Database: SQLite3 with FTS5 virtual tables for high-speed full-text search
Embedding Model: nomic-embed-text-v1.5 (768-dimension, local execution)
Knowledge Base: Google Takeout, Obsidian, and Markdown documents (6,000 items, 180MB)
Search Method: Hybrid RAG combining keyword matching with vector similarity search
LLM Orchestration
Multi-Provider Support: Cerebras (Llama-3.1-70B), Groq, NVIDIA Kimi, Gemini 3.0, 3.1
Fallback Logic: Automatically switches to next provider on API error or 429 response (delay under 2 seconds)
Communication Protocol: OpenAI-compatible API with SSE real-time streaming
Interface and Security
Web UI: Lightweight conversation window based on http.server with SSE real-time rendering
CLI: curl-based command execution and direct terminal control
Security: Local host binding (127.0.0.1) with whitelist IP access control
Backup Strategy: tar.gz automatic scheduling with dual backup in Download folder
Autonomy Metrics
Self-Modification: 3 limited code modification rights combining tool:patch and GarlicLang
Meta-Cognition: SOUL.md-based role definition with immediate rule reflection during incidents (Layer 0-2 architecture)
Conclusion and Future Vision
Realization of Decentralized Personal AI
The Garlic Agent project proves that one can build an independent knowledge base and autonomous engine within a personally-owned mobile device (Unihertz Titan2) without relying on large corporations' cloud infrastructure. This represents a practical implementation of data sovereignty and AI autonomy combined. Though built from existing concepts, the integration is novel and powerful.
Garlic Farmer and AI Symbiosis
The project's core strength lies in meta-cognitive collaboration where AI transcends being a mere tool and learns system rules (SOUL.md) independently, quickly supplementing them when incidents occur. Garlic Farmer provides infrastructure direction, while AI validates logical integrity through GarlicLang and expands the system's capabilities.
Future Roadmap
VFS Mirroring Enhancement: Build perfect synchronization with external storage beyond Termux environment and implement comprehensive virtual file system
Multi-Agent Discussion System (Garlic Talk): Achieve collective intelligence by having multiple agents using different LLMs discuss and collaborate to derive optimal solutions
Embedded Autonomous Tuning: Real-time optimization of embedding models and search weights based on user conversation patterns and work historyโa self-evolving RAG system
Complete Isolation Sandbox: Apply more powerful execution security and resource limiting in GarlicLang v30 and beyond for enhanced safety
A Comma, Not a Period
Garlic Terminal is not a finished product but a constantly evolving organism. On any given day, hundreds of errors are being processed in real-time through collaboration with multiple AI providers. The trial-and-errors like the backup disaster of February 2026 are becoming fertilizer that makes the system stronger. I believe that without a PC, without significant capital, with only code, logic, and life philosophy, one can build a personal AI ecosystem.
Appendix A: GarlicLang Detailed Syntax and Execution Flow
Block Structure and Operations
GarlicLang operates on a block-by-block basis enclosed in square brackets ([]). [execute] ls -la /garlic-agent executes bash commands through subprocess.run(). [output] Current time is {time} outputs text with variable substitution support. [set_variable] count = 5 stores internal variables. [condition] {count} > 3 performs branching with different execution paths. [repeat] 3 executes loops. [verify] file_exists /garlic-agent/web.py returns PASS/FAIL results.
Execution Flow Pipeline
User natural language input is converted to GarlicLang script by LLM, which is then parsed by garliclang_bridge.py. Each block is executed sequentially with a 30-second timeout. Results are wrapped in JSON and transmitted via SSE to the UI. Dangerous commands (rm -rf, mkfs, etc.) are blocked in advance by pattern matching.
Automatic Verification Mechanism
The [verify] block checks AI claims against actual system state. For example, if AI claims "the file exists," [verify] file_exists path confirms it. If PASS/FAIL results mismatch, it's classified as hallucination and the user is warned immediately.
Appendix B: Similar Technology Comparison
Feature Comparison Matrix
| Feature | Garlic Terminal | GitHub Copilot CLI | Amazon Q CLI | ChatGPT/Claude |
|---|---|---|---|---|
| Execution Environment | Android Termux | PC/Mac | PC/Mac/Linux | Web/API |
| Korean Language Support | Native | Limited | Limited | Supported |
| Intermediate Language (DSL) | GarlicLang | None | None | None |
| Local Code Execution | Yes (Sandbox) | Yes | Yes | No (API only) |
| Hybrid RAG Search | Yes (FTS5+Vector) | No | No | No |
| Hallucination Prevention | Auto Verify+Cross Verify | No | No | No |
| Offline Capability | Partial (Local LLM) | No | No | No |
| Multi-LLM Fallback | Yes (CerebrasโGeminiโDeepSeek) | No | No | No |
| Cost Model | Partially Free (API Free Tier) | Paid | Paid | Paid |
Key Differentiator: Through the intermediate language GarlicLang, AI writes a plan rather than directly manipulating the system, simultaneously solving security and cost issues.
Appendix C: Development Timeline
Phase 1: Foundation Building (2026-02-22)
Termux environment setup, Python package installation, basic web.py HTTP server implementation, initial LLM API integration (Cerebras).
Phase 2: RAG System Development (2026-02-23)
knowledge.db creation with FTS5 full-text search, nomic-embed-text vector embedding adoption, hybrid search logic implementation, 5,800+ document automatic indexing pipeline completion. This phase consolidated conversations from tens of thousands of AI interactions spanning two years. Over ten thousand chat sessions were opened and processed, allowing organization of the most valuable personal knowledge resources.
Phase 3: GarlicLang and Security Enhancement (2026-02-24)
GarlicLang DSL design and interpreter implementation, garliclang_bridge.py completion, dangerous command blocking through pattern matching, SOUL.md backup policy establishment with triple redundancy.
Phase 4: Stabilization and Autonomous Operation (2026-02-25)
chat_sessions.db conversation saving bug fixes (conv_id=9), HUD web and wake status display additions, startall.sh llama default set to OFF for memory conservation, llamaon/llamaoff alias registration, archive_chat.py for date-based conversation archiving, watchdog.sh llama auto-restart disabling, integrated whitepaper v2 composition.
Appendix D: Prompt Engineering Evolution
Generation 1: Initial Prompt (v0.1)
Simple directive approach: "Answer the user's question." Results showed frequent hallucinations and numerous system command misexecutions.
Generation 2: Structured Prompt (v0.5)
Incorporated role assignment and context injection. Achieved 60% reduction in hallucination rate but still struggled with complex multi-step tasks.
Generation 3: Current Prompt (v1.0)
SOUL.md-based self-definition combined with RAG context, explicit tool listing, and forbidden pattern enumeration. System prompt includes SOUL.md in full, top 5 RAG context injection, complete tool list, forbidden command pattern library, and enforced response formatting.
Key Lesson
Prompts function as code. A single-line instruction change determines entire system stability. Positive directives ("do this") prove more effective than negative ones ("don't do that"). Accuracy increases dramatically when concrete examples are provided.
Appendix E: Real-World Usage Scenarios
Scenario 1: Document Search
User: "Find documents related to meta-cognition protocol"
Process: Hybrid RAG search with keyword and vector matching
Output: Top 3 relevant documents with summaries
Scenario 2: System Management
User: "Check disk usage"
Process: GarlicLang conversion to [execute] df -h command
Output: Natural language summary of disk space allocation
Scenario 3: File Modification
User: "Change port number to 8081 in web.py"
Process: tool:read file โ tool:patch modification โ AST verification โ save
Output: Confirmation of successful modification
Scenario 4: Interactive Debugging
User: "Server won't start. Check logs"
Process: [execute] tail -20 ~/garlic-agent/web.log โ error pattern analysis
Output: Root cause identification with recommended solutions
Scenario 5: Backup and Recovery
User: "Full backup please"
Process: Execute backup.sh โ Create tar.gz archive
Output: Confirmation with archive size and location
Appendix F: Multi-Provider LLM Orchestration
Provider Priority Hierarchy
- Cerebras (Llama 70B) โ Free tier, fastest response, primary choice
- Gemini 3.0 Flash โ Paid tier, highly stable, secondary choice
- DeepSeek V3 โ Paid tier, superior Korean language handling, tertiary choice
Fallback Logic and Switching
The call_llm() function sequentially attempts providers in priority order. On 1st priority failure, automatically switches to 2nd priority with delay under 2 seconds. If all providers fail, returns error message. Maximum retry count is 2 per provider.
Cross-Verification for Critical Responses
Important responses undergo verification through different provider. If similarity between responses falls below 70%, triggers hallucination suspicion warning. The call_llm_verify() function performs this automatically.
Final Notes
Integrated Whitepaper Completion: 2026-02-25
Total Content: 10 Chapters + 6 Appendices
Document Version: 2.0
Created by: Garlic Farmer + Garlic Agent (Claude Opus 4.6 + Gemini)
Though I am merely a Korean garlic farmer without expensive computing equipment, I accomplished this ambitious project. It represents two years of continuous effort, learning, and perseverance through numerous challenges. This achievement demonstrates that with determination, code, logic, and philosophical commitment, one can build powerful personal AI systems accessible to anyone with modest resources.
Top comments (0)