{"id":34599236,"url":"https://github.com/niradler/termu","last_synced_at":"2026-05-26T00:32:13.363Z","repository":{"id":319737258,"uuid":"1075713800","full_name":"niradler/termu","owner":"niradler","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-19T21:12:05.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-25T23:46:52.921Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niradler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-13T22:16:17.000Z","updated_at":"2025-10-19T21:12:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"e0cdb1ad-01a5-41d4-a5dc-de345509e58d","html_url":"https://github.com/niradler/termu","commit_stats":null,"previous_names":["niradler/termu"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/niradler/termu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Ftermu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Ftermu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Ftermu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Ftermu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niradler","download_url":"https://codeload.github.com/niradler/termu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Ftermu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33498842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T12:07:50.172Z","updated_at":"2026-05-26T00:32:13.342Z","avatar_url":"https://github.com/niradler.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# termu - Your Terminal Sidekick\n\ntermu is a terminal chat agent that helps you accomplish tasks using shell commands. Have conversations with termu, and it will assist you through intelligent command execution - all while keeping you in control.\n\n## Overview\n\ntermu is your terminal sidekick - a conversational AI agent that understands what you want to accomplish and helps you get there. Powered by local LLMs (via Ollama) or OpenAI-compatible servers (like LiteLLM), termu can directly read and edit files, execute shell commands for exploration, and leverage modern cross-platform CLI tools - all while keeping you in control with session-based command approval.\n\n## Features\n\n### 💬 Conversational AI Agent with Direct File Access\n\n- Natural language interactions - just tell termu what you need\n- Direct filesystem access through structured tool calling\n- Can read, write, and surgically edit files without shell commands\n- Multi-turn conversations with context awareness\n- Session-based command approval (approve once per session)\n- Runs in your current working directory context\n- Powered by Ollama (default: Qwen3 model) or OpenAI-compatible servers (LiteLLM, etc.)\n\n### 💬 Chat-First Experience\n\n- Rich interactive chat mode powered by [Bubble Tea](https://github.com/charmbracelet/bubbletea)\n- Markdown-formatted responses with [Glow](https://github.com/charmbracelet/glow)\n- Command preview before execution with syntax highlighting\n- Session-based conversation history\n- Split-pane interface: chat on left, execution on right\n- Approve/reject commands with simple keyboard shortcuts\n\n### 🔒 Safe Command Execution\n\n- **Session-Based Approval**: Approve/reject commands before execution; approvals persist for the entire session\n- **Current Directory Context**: All commands run in the folder where termu was launched\n- **Command Whitelist**: Control which commands termu can use\n- **Destructive Action Guard**: Prevents dangerous operations\n- **Sandbox Mode**: Test behavior without actually executing commands\n\n### ⚡ Smart Tool Selection\n\ntermu favors modern, cross-platform CLI tools to accomplish tasks efficiently. You don't need to know how to use them - termu handles that:\n\n| Tool                                             | Purpose           | Why It's Better                          |\n| ------------------------------------------------ | ----------------- | ---------------------------------------- |\n| [sd](https://github.com/chmln/sd)                | Search \u0026 replace  | Simpler than sed, more intuitive         |\n| [fd](https://github.com/sharkdp/fd)              | File finding      | 3x faster than find, user-friendly       |\n| [ripgrep](https://github.com/BurntSushi/ripgrep) | Content search    | 5x faster than grep, respects .gitignore |\n| [bat](https://github.com/sharkdp/bat)            | File preview      | Syntax highlighting, Git integration     |\n| [xsv](https://github.com/BurntSushi/xsv)         | CSV toolkit       | Fast CSV processing and analysis         |\n| [jaq](https://github.com/01mf02/jaq)             | JSON processing   | Faster jq alternative                    |\n| [yq](https://github.com/mikefarah/yq)            | YAML/JSON         | Universal config file manipulation       |\n| [dua](https://github.com/Byron/dua-cli)          | Disk analysis     | Interactive disk usage visualization     |\n| [eza](https://eza.rocks/)                        | Directory listing | Modern ls with colors and Git status     |\n\n### 🛠️ Structured Tool Calling\n\ntermu uses [Genkit's tool calling feature](https://genkit.dev/docs/tool-calling/?lang=go) for intelligent filesystem operations and command execution. Instead of relying solely on shell commands, termu has direct access to structured tools for file manipulation and code editing.\n\n**Available Tools:**\n\n| Tool              | Purpose                           | When to Use                                                    |\n| ----------------- | --------------------------------- | -------------------------------------------------------------- |\n| `read_file`       | Read complete file contents       | Understanding code, checking implementations, reviewing files  |\n| `write_file`      | Create or completely overwrite    | Creating new files, major rewrites (overwrites entire content) |\n| `search_replace`  | Exact string search and replace   | Targeted edits, renaming, bug fixes, surgical code changes     |\n| `list_directory`  | List files and directories        | Exploring project structure, finding files (with recursion)    |\n| `execute_command` | Run shell commands in working dir | Searching (fd/rg), git operations, previews (bat/eza)          |\n| `read_clipboard`  | Read system clipboard content     | Accessing copied text, working with clipboard data             |\n| `write_clipboard` | Write content to system clipboard | Copying results, sharing data between applications             |\n\n**Benefits of Structured Tool Calling:**\n\n- **Direct file access**: Read and write files without shell command parsing\n- **Surgical edits**: Make precise changes with `search_replace` without rewriting entire files\n- **Reliability**: Structured JSON interfaces eliminate command parsing ambiguity\n- **Multi-step workflows**: Read → analyze → edit → verify in one conversation\n- **Hybrid approach**: Direct file operations + shell commands for exploration\n- **Context awareness**: All operations run in your current working directory\n\n## Installation\n\n### Prerequisites\n\n1. **Go 1.23+**\n2. **Ollama** - [Download](https://ollama.com/download)\n3. **Qwen3 Model** (or your preferred model):\n   ```bash\n   ollama pull qwen3\n   ```\n\n### Install termu\n\n```bash\ngo install github.com/niradler/termu/cmd/termu@latest\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/niradler/termu.git\ncd termu\ngo build -o termu cmd/termu/main.go\n```\n\n### Install Favorite Cross-Platform Tools\n\ntermu works with standard commands but is supercharged with these modern tools. The built-in installer can help you set them up:\n\n**macOS (Homebrew):**\n\n```bash\nbrew install sd fd ripgrep bat xsv yq dua-cli eza\nbrew install jaq\n```\n\n**Linux (Cargo):**\n\n```bash\ncargo install sd fd-find ripgrep bat xsv jaq dua-cli eza\n```\n\n**Windows (Scoop):**\n\n```bash\nscoop install sd fd ripgrep bat yq dua eza\ncargo install xsv jaq\n```\n\n## Configuration\n\nCreate `.termu.yaml` in your home directory or project root:\n\n```yaml\n# AI Model Configuration\nmodel:\n  provider: ollama # Options: \"ollama\" (default) or \"openai\" (for OpenAI-compatible servers)\n  name: qwen3 # Model name\n  server: http://127.0.0.1:11434 # Ollama server address (for ollama provider)\n  timeout: 60 # Request timeout in seconds\n\n  # For OpenAI-compatible servers (e.g., LiteLLM, custom OpenAI endpoints)\n  # api_key: \"sk-1234\"           # Your API key (required for openai provider)\n  # base_url: \"http://localhost:4000/v1\"  # Custom endpoint URL (required for openai provider)\n\n# Security Configuration\nsecurity:\n  # Command whitelist (empty = allow all from safe_commands list)\n  allowed_commands:\n    - sd\n    - fd\n    - rg\n    - bat\n    - xsv\n    - jaq\n    - yq\n    - dua\n    - eza\n    - ls\n    - cat\n    - grep\n    - find\n    - echo\n    - pwd\n    - cd\n    - git\n    - curl\n    - wget\n\n  # Restricted folders (agent cannot access these)\n  restricted_folders:\n    - /System\n    - /Windows\n    - /etc/passwd\n    - /etc/shadow\n    - ~/.ssh\n    - ~/.aws\n\n  # Allowed folders (when set, restricts to these only)\n  allowed_folders:\n    - ./\n    - ~/Documents\n    - ~/Projects\n\n  # Commands that always require approval\n  high_risk_commands:\n    - rm\n    - mv\n    - chmod\n    - chown\n    - sudo\n    - curl -X POST\n    - wget -O\n\n  # Destructive patterns (always blocked)\n  blocked_patterns:\n    - \"rm -rf /\"\n    - \"rm -rf *\"\n    - \":(){ :|:\u0026 };:\" # fork bomb\n    - \"mkfs\"\n    - \"dd if=\"\n    - \"\u003e /dev/sda\"\n\n# Logging\nlogging:\n  level: info\n  file: ~/.termu/logs/termu.log\n```\n\n### Using OpenAI-Compatible Servers (LiteLLM, etc.)\n\ntermu supports OpenAI-compatible servers like [LiteLLM](https://docs.litellm.ai/), allowing you to use various LLM providers through a unified API:\n\n```yaml\nmodel:\n  provider: \"openai\" # Use OpenAI-compatible provider\n  name: \"gpt-4\" # Model name (depends on your server config)\n  api_key: \"sk-1234\" # API key (required)\n  base_url: \"http://localhost:4000/v1\" # Custom endpoint URL\n  timeout: 60\n```\n\n**Example: Running with LiteLLM**\n\n1. Start LiteLLM server:\n\n   ```bash\n   litellm --model gpt-4 --api_base http://localhost:4000\n   ```\n\n2. Configure `.termu.yaml` with the settings above\n\n3. Start termu:\n   ```bash\n   termu chat\n   ```\n\nSee `.termu.openai.example.yaml` for a complete example configuration.\n\n## Usage\n\n### Start a Chat Session\n\n```bash\ntermu chat\n```\n\nThis starts an interactive session where you can have a conversation with termu. Tell it what you want to accomplish, and it will suggest commands to help.\n\n**Chat Features:**\n\n- 💬 Natural conversation - just describe what you want\n- 🎨 Beautiful split-pane interface\n- 📝 Markdown-formatted responses\n- ✅ Approve/reject commands before execution\n- 🔄 Session-based approval - approve once, reuse for similar commands\n- 📂 Commands run in your current working directory\n- 📜 Full conversation history within the session\n\n**Keyboard Shortcuts:**\n\n- `Enter` - Send message / Approve command\n- `Esc` - Reject command\n- `Ctrl+C` - Cancel operation\n- `Ctrl+D` - Exit session\n- `↑/↓` - Navigate history\n- `Ctrl+L` - Clear screen\n\n### Quick Command\n\n```bash\ntermu \"find all Python files modified in the last week\"\n```\n\n### Custom Config\n\n```bash\ntermu --config ./custom-config.yaml chat\n```\n\n## How It Works\n\n1. **Start a Session**: Launch `termu chat` in any directory\n2. **Have a Conversation**: Tell termu what you want to accomplish in natural language\n3. **AI Understanding**: Local LLM (via Ollama) or OpenAI-compatible server understands your request\n4. **Smart Tool Selection**: termu chooses the best approach - direct file operations or shell commands\n5. **Preview \u0026 Approval**: See exactly what termu will do (read/edit files or run commands)\n6. **Your Control**: Approve or reject; approvals are remembered for the session\n7. **Execution in Context**: Operations run in your current working directory\n8. **Continue the Conversation**: Discuss results, refine, or move to the next task\n\n## Sessions \u0026 Command Approval\n\ntermu uses a session-based approval system:\n\n- **First Time**: When termu wants to run a command, you approve or reject it\n- **Within Session**: Once approved, similar commands in the same session don't require re-approval\n- **Session End**: When you exit termu, approval history is cleared\n- **New Session**: Fresh start with new approval requirements\n\nThis gives you control while keeping the conversation flowing naturally.\n\n## Security Best Practices\n\n1. **Review Before Approving**: Always check the command preview\n2. **Session Awareness**: Remember that approvals persist throughout your session\n\n## Example Conversations\n\nHere are some examples of what you can ask termu:\n\n### File Management \u0026 Code Editing\n\n- \"Read the README.md and update the installation section\"\n- \"Find all TODO comments in TypeScript files and list them\"\n- \"Replace all occurrences of 'oldFunction' with 'newFunction' in src/utils.go\"\n- \"Create a new config.yaml file with database settings\"\n\n### Data Analysis \u0026 Processing\n\n- \"Find duplicate files by name in ./downloads\"\n- \"Search for the most common error in log files using ripgrep\"\n- \"Show me the largest files taking up disk space\"\n- \"Convert all YAML configs to JSON\"\n\n### Code Exploration\n\n- \"List all Go files in the project recursively\"\n- \"Show me what changed in the last 5 git commits\"\n- \"Preview the main.go file with syntax highlighting\"\n- \"Find files that haven't been modified in 6 months\"\n\n## Troubleshooting\n\n### Ollama Connection Issues\n\n```bash\n# Check if Ollama is running\nollama list\n\n# Verify model is installed\nollama pull qwen3\n\n# Test connection\ncurl http://127.0.0.1:11434/api/tags\n```\n\n### Command Not Whitelisted\n\nAdd the command to your `.termu.yaml`:\n\n```yaml\nsecurity:\n  allowed_commands:\n    - your_command\n```\n\n## Development\n\n### Project Structure\n\n```\ntermu/\n├── cmd/termu/           # CLI entry point\n├── internal/\n│   ├── agent/           # Genkit agent implementation\n│   ├── security/        # Security validators and approvals\n│   ├── shell/           # Shell execution in cwd context\n│   ├── tools/           # Tool management and installer\n│   ├── tui/             # Interactive chat interface\n│   └── config/          # Configuration handling\n├── go.mod\n└── README.md\n```\n\n### Running Tests\n\n```bash\ngo test ./...\n```\n\n### Building\n\n```bash\ngo build -o termu cmd/termu/main.go\n```\n\n## Roadmap\n\n- [ ] Enhanced conversation memory across sessions\n- [ ] Support for additional models providers\n- [ ] MCP Servers support\n- [ ] Multi-session management\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Credits\n\nBuilt with:\n\n- [Genkit](https://genkit.dev/) - AI workflow framework\n- [Ollama](https://ollama.com/) - Local LLM runtime\n- [Cobra](https://cobra.dev/) - CLI framework\n- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework\n- [Lip Gloss](https://github.com/charmbracelet/lipgloss) - Terminal styling\n- [Glow](https://github.com/charmbracelet/glow) - Markdown rendering\n- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components\n- Amazing Rust/Go CLI tools that make termu powerful\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Ftermu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniradler%2Ftermu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Ftermu/lists"}