{"id":50911039,"url":"https://github.com/seedcodes/rook","last_synced_at":"2026-06-16T10:02:09.295Z","repository":{"id":362118125,"uuid":"1257413477","full_name":"SeedCodes/rook","owner":"SeedCodes","description":"System-aware AI terminal copilot for Linux. Watches your shell, understands your machine, and answers with context.","archived":false,"fork":false,"pushed_at":"2026-06-02T17:04:34.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T19:11:41.242Z","etag":null,"topics":["ai","bash","copilot","linux","ollama","shell","terminal","zsh"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/SeedCodes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2026-06-02T16:50:25.000Z","updated_at":"2026-06-02T17:04:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SeedCodes/rook","commit_stats":null,"previous_names":["seedcodes/rook"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SeedCodes/rook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeedCodes%2Frook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeedCodes%2Frook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeedCodes%2Frook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeedCodes%2Frook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SeedCodes","download_url":"https://codeload.github.com/SeedCodes/rook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeedCodes%2Frook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34400456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai","bash","copilot","linux","ollama","shell","terminal","zsh"],"created_at":"2026-06-16T10:02:08.286Z","updated_at":"2026-06-16T10:02:09.286Z","avatar_url":"https://github.com/SeedCodes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⬛ Rook\n\n\u003e Your terminal, with memory. A context-aware AI copilot that knows your machine, your commands, and your mistakes.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](CHANGELOG.md)\n[![Linux](https://img.shields.io/badge/platform-Linux-lightgrey.svg)](#prerequisites)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)\n[![Tests](https://img.shields.io/badge/tests-34%20passing-brightgreen.svg)](tests/)\n\n---\n\n## What can it do?\n\nRook turns your terminal into an AI-powered workbench. It **scans your entire system** on install, **watches everything you do**, and gives you an AI assistant that already knows your machine when you ask for help.\n\n**It knows:**\n- Your OS, kernel, CPU, RAM, disk\n- Every package installed via apt/pip/npm/cargo\n- All running services\n- Your home directory structure\n- Your dotfiles (`.zshrc`, `.gitconfig`, etc.)\n- Every git repo you have\n- All your Docker images\n- Every command you've run (with exit codes)\n- The full output of your last terminal session\n\n**It can:**\n- Diagnose failed commands in one shot\n- Answer questions about your machine without you explaining it\n- Suggest fixes that match your actual installed tools\n- Continue a conversation with full context of what you tried\n- Run completely offline via Ollama\n\n---\n\n## Demo\n\n### Debug a failed command — Rook already saw it\n\n```bash\n$ docker run hello-world\ndocker: error during connect: cannot connect to daemon\n$ rook chat\n# → new terminal opens\nyou ▸ why did docker fail?\nRook: The Docker daemon isn't running. On this system (Ubuntu 26.04),\n      start it with: sudo systemctl start docker\n      Then add yourself to the docker group: sudo usermod -aG docker $USER\n```\n\n### Ask about your system — no setup needed\n\n```bash\n$ rook query \"what's the best way to free up disk space on this machine?\"\nRook: You have 380G free out of 500G, so disk isn't critical.\n      Top space consumers I can see:\n        - /var/log (~8G, mostly old journal files)\n        - ~/.cache (3.2G, safe to clear)\n        - Docker images: 12.4G total\n      Try: sudo journalctl --vacuum-time=2w  and  docker system prune -a\n```\n\n### Multi-turn chat with full terminal context\n\n```bash\n$ rook on\n$ cat /etc/nginx/sites-enabled/default\n# ... see nginx config ...\n$ nginx -t\nnginx: [emerg] unknown directive \"server_nam\" in /etc/nginx/sites-enabled/default:42\n$ rook chat\nyou ▸ what does that nginx error mean?\nRook: You have a typo on line 42 — \"server_nam\" should be \"server_name\".\n      I can see your config has: server_nam example.com;\n      Fix: change line 42 to read:  server_name example.com;\n\nyou ▸ also check for other typos\nRook: Looking at your config... line 47 has \"listen 80 default_servr;\" — \n      another typo, should be \"default_server\".\n```\n\n### Inline queries — no need to open a window\n\n```bash\n$ ?? find all python files modified in the last day\nRook: find . -name \"*.py\" -mtime -1 -type f\n\n$ ?? how do I enable syntax highlighting in nano\nRook: Edit ~/.nanorc and add: include /usr/share/nano/*.nanorc\n```\n\n---\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **System scanner** | On install, captures OS, packages, services, projects, dotfiles, git repos, Docker images, venvs, PATH binaries |\n| **Live terminal recording** | When `rook on` is active, every command + output is captured to `recording.log` via `script` |\n| **Structured command log** | Every command logged with timestamp + exit code for precise error correlation |\n| **Error diagnosis** | When a command fails, run `rook chat` — Rook already knows the error |\n| **Local AI** | Powered by [Ollama](https://ollama.com) — no API keys, no cloud, fully private |\n| **Multi-turn chat** | `rook chat` opens a new terminal with conversation memory |\n| **Inline queries** | `?? your question` in any shell prompt for instant answers |\n| **Web search** | Augments queries with current web results when needed (docs, latest versions) |\n| **Shell hooks** | `preexec`/`precmd` capture everything without affecting your workflow |\n| **Zero config** | Works out of the box with `gemma3:1b`; swap to `llama3.2:3b` for smarter responses |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Linux** (Ubuntu, Fedora, Arch, etc.)\n- **Python 3.8+**\n- **`gnome-terminal`** — for the chat window\n- **`script`** — from `util-linux` (preinstalled on most distros)\n- **[Ollama](https://ollama.com/download)** — local AI runtime\n\n### Install\n\n```bash\ngit clone https://github.com/SeedCodes/rook.git\ncd rook\nbash install.sh\n```\n\nRestart your shell:\n```bash\nsource ~/.zshrc   # or source ~/.bashrc\n```\n\nPull a model and turn Rook on:\n```bash\nollama pull gemma3:1b\nrook on\n```\n\nThat's it. Rook is now watching your terminal.\n\n---\n\n## Usage\n\n| Command | Action |\n|---------|--------|\n| `rook` | Toggle on/off |\n| `rook on` | Turn on + start recording |\n| `rook off` | Turn off |\n| `rook scan` | Re-scan system, rebuild context |\n| `rook query \u003cquestion\u003e` | Ask a single question (one-shot) |\n| `rook chat` | Open chat in a new terminal (multi-turn) |\n| `?? \u003cquestion\u003e` | Inline query at any prompt |\n| `rook config` | Edit config in `$EDITOR` |\n| `rook status` | Show current state |\n| `rook update` | Pull latest version |\n\n---\n\n## Real workflows\n\n### 1. Diagnose anything instantly\n\n```bash\n$ apt install dockr\nE: Unable to locate package dockr\n$ rook chat\nyou ▸ I tried to install dockr\nRook: Typo — the package is \"docker.io\" on Debian/Ubuntu.\n      Try: sudo apt install docker.io\n```\n\n### 2. Explore your own machine\n\n```bash\n$ rook query \"what services are running on this system?\"\n$ rook query \"show me my python virtual environments\"\n$ rook query \"which docker images do I have and how big are they?\"\n$ rook query \"what's the disk usage of my home directory?\"\n```\n\n### 3. Learn while you work\n\n```bash\n$ curl -fsSL https://get.docker.com | sh\n# ... 200 lines of output ...\n$ rook query \"explain what that docker install script just did\"\n```\n\n### 4. Recover from mistakes\n\n```bash\n$ rm -rf ~/projects/important-thing\n# oh no\n$ rook chat\nyou ▸ I just deleted a project folder, can I recover it?\nRook: If the filesystem is ext4 and you act fast, you might be able to\n      recover files using extundelete. Stop writing to the disk now.\n      Install with: sudo apt install extundelete\n      Then: sudo extundelete /dev/sdaX --restore-directory ~/projects\n```\n\n---\n\n## Configuration\n\nEdit `~/.rook/config.json`:\n\n```json\n{\n  \"model\": \"gemma3:1b\",\n  \"ollama_url\": \"http://localhost:11434\",\n  \"web_search\": true,\n  \"theme\": \"dark\",\n  \"scan_on_startup\": false,\n  \"error_hook\": true,\n  \"query_prefix\": \"??\"\n}\n```\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `model` | `gemma3:1b` | Ollama model to use |\n| `ollama_url` | `http://localhost:11434` | Ollama API endpoint |\n| `web_search` | `true` | Augment queries with web search for current info |\n| `query_prefix` | `??` | Inline query prefix |\n| `error_hook` | `true` | Auto-capture failed commands |\n| `scan_on_startup` | `false` | Re-scan on every shell start (slow) |\n\n**Recommended models:**\n- `gemma3:1b` — tiny (815MB), works everywhere, basic reasoning\n- `llama3.2:3b` — better reasoning, 2GB\n- `deepseek-coder:1.3b` — best for code questions, 776MB\n- `llama3.2:1b` — alternative to gemma3, similar size\n\n---\n\n## How It Works\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ Your terminal                                                │\n│  ┌────────────────────────────────────┐                      │\n│  │ You type commands                  │                      │\n│  │   preexec → logs command string    │                      │\n│  │   script   → records full output   │                      │\n│  │   precmd  → logs exit code         │                      │\n│  └────────────────┬───────────────────┘                      │\n└───────────────────┼──────────────────────────────────────────┘\n                    │  rook chat / rook query / ??\n                    ▼\n        ┌─────────────────────────────────┐\n        │ rook.py                         │\n        │   • Reads context.json          │\n        │   • Reads terminal.log          │\n        │   • Reads recording.log         │\n        │   • Builds system prompt        │\n        │   • Sends to Ollama (local)     │\n        └────────────────┬────────────────┘\n                         │\n                         ▼\n                ┌─────────────────┐\n                │ Ollama          │\n                │ (local AI)      │\n                │ 127.0.0.1:11434 │\n                └─────────────────┘\n```\n\n1. **System scan** — On install, Rook dumps your machine state to `~/.rook/context.json` (OS, packages, projects, dotfiles, etc.)\n2. **Shell hooks** — `preexec` saves the command, `script` records output, `precmd` saves exit code — all in real time\n3. **AI query** — When you ask, Rook assembles a system prompt with: system context + recent commands + terminal output\n4. **Local inference** — Ollama runs the model locally. Nothing leaves your machine.\n\n---\n\n## Troubleshooting\n\n**\"ollama: command not found\"**\n```bash\ncurl -fsSL https://ollama.com/install.sh | sh\nollama pull gemma3:1b\n```\n\n**\"gnome-terminal: command not found\"**\n```bash\nsudo apt install gnome-terminal    # Ubuntu/Debian\nsudo dnf install gnome-terminal    # Fedora\n```\n\n**Model gives poor responses**\nTry a bigger model:\n```bash\nollama pull llama3.2:3b\n# then edit ~/.rook/config.json: \"model\": \"llama3.2:3b\"\n```\n\n**Chat window doesn't open**\nCheck that you're on X11 or Wayland with XWayland, and that `gnome-terminal` opens manually.\n\n**\"Rook recording stopped\" appears unexpectedly**\nThe `script` session ended (you typed `exit` or the shell process exited). Run `rook on` again.\n\n**Want to clear old recordings?**\n```bash\nrm ~/.rook/recording.log ~/.rook/terminal.log\n```\n\n---\n\n## Uninstall\n\n```bash\nbash uninstall.sh\n```\n\nRemoves `~/.rook/`, source lines from `.zshrc`/`.bashrc`, and stops all Rook processes.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\n[MIT](LICENSE) © 2026 SeedCodes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseedcodes%2Frook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseedcodes%2Frook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseedcodes%2Frook/lists"}