{"id":50307258,"url":"https://github.com/hra42/ai","last_synced_at":"2026-05-28T17:30:41.835Z","repository":{"id":355502042,"uuid":"1228124094","full_name":"hra42/ai","owner":"hra42","description":"A minimal AI shell assistant CLI in Go. Natural language to shell commands with TUI review.","archived":false,"fork":false,"pushed_at":"2026-05-03T23:18:52.000Z","size":1976,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T00:33:24.016Z","etag":null,"topics":["ai","assistant","automation","cli","golang","openrouter","shell","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hra42.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":"2026-05-03T16:17:35.000Z","updated_at":"2026-05-03T23:18:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hra42/ai","commit_stats":null,"previous_names":["hra42/ai"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/hra42/ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hra42","download_url":"https://codeload.github.com/hra42/ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hra42%2Fai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33619965,"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-05-28T02:00:06.440Z","response_time":99,"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","assistant","automation","cli","golang","openrouter","shell","terminal","tui"],"created_at":"2026-05-28T17:30:39.230Z","updated_at":"2026-05-28T17:30:41.822Z","avatar_url":"https://github.com/hra42.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"left\"\u003e\n  \u003cimg src=\"./media/images/icon.png\" alt=\"ai logo\" width=\"96\" /\u003e\n\u003c/p\u003e\n\n# ai\n\nA minimal AI shell assistant CLI in Go. Type a request in natural language, get a shell command back — review it in a TUI, run it on enter.\n\n```\n$ ai list all files with .go extension\n\n  Suggested command\n  ╭─────────────────────────────╮\n  │ find . -name '*.go' -type f │\n  ╰─────────────────────────────╯\n  Lists all .go files in the current directory and below.\n  [enter/y] run · [esc/n] cancel\n```\n\n## Install\n\n### Homebrew (macOS, Linux)\n\n```sh\nbrew install hra42/tap/ai\n```\n\n### Install script (macOS, Linux)\n\n```sh\ncurl -fsSL https://ai.hra42.lol/install | sh\n```\n\nPicks the right binary for your OS/arch, verifies the SHA-256 from `checksums.txt`, and drops it into `/usr/local/bin` (override with `INSTALL_DIR=…`). Pin a version with `VERSION=v0.1.4`.\n\n### `go install`\n\n```sh\ngo install github.com/hra42/ai@latest\n```\n\n### Pre-built binaries\n\nGrab a tarball for your OS/arch from the [Releases page](https://github.com/hra42/ai/releases) and drop the `ai` binary into your `$PATH`.\n\n### From source\n\n```sh\ngit clone https://github.com/hra42/ai\ncd ai\ngo build -o ai .\n```\n\nCheck the installed version with `ai --version`.\n\n## First run\n\nOn first launch (no config) `ai` walks you through a TUI setup wizard:\n\n1. **API key source** — pick one:\n   - Save plaintext in `~/.config/ai/config.yaml`\n   - Read from 1Password via secret reference (`op://Vault/Item/field`)\n   - Use `$OPENROUTER_API_KEY` env var only (nothing saved)\n2. **Model** — fuzzy-search the live OpenRouter model catalog. Hit ↑/↓, enter to pick.\n\nRe-run setup any time by deleting `~/.config/ai/config.yaml`.\n\n## Usage\n\n### Command mode (default)\n\n```sh\nai \u003crequest\u003e\n```\n\nGenerates a shell command, shows it in a review TUI with a one-line explanation, runs it on `enter`. Cancel with `esc`/`n`. Executed commands land in your zsh history.\n\n![Basics demo](./media/ai_demos/gifs/01_basic.gif)\n\n### Chat mode\n\n```sh\nai -c \u003cquestion\u003e\n```\n\nFree-form Q\u0026A. If the answer naturally implies a command (and it's actually runnable — no placeholders), the TUI offers to run it.\n\n```sh\nai -c \"what does chmod 755 do\"            # explanation only\nai -c \"how do I list .go files\"           # explanation + suggested command\n```\n\n![Chat demo](./media/ai_demos/gifs/03_chat.gif)\n\n### Pipe support\n\n```sh\ncat error.log | ai explain the error\nps aux | ai -c \"which process is using the most memory\"\n```\n\nPiped stdin is appended to the prompt as additional context. The review TUI still works because input is read from `/dev/tty`.\n\n![Pipe demo](./media/ai_demos/gifs/02_pipe.gif)\n\n### Flags\n\n| Flag | Purpose |\n|---|---|\n| `-c, --chat` | Chat mode — answer the question, optionally suggest a command |\n| `-y, --yes` | Skip confirmation, run the command directly (for scripts) |\n| `-p, --print` | Print the command and exit, don't execute |\n| `--model \u003cid\u003e` | Override the configured model for this call |\n\n`--yes` and `--print` are required for non-TTY use (CI, pipes); without one of them the CLI errors out instead of running silently.\n\n## Context\n\nEach request includes lightweight environment context so the model can tailor commands to your system:\n\n- **Static**: OS (`darwin`/`linux`), shell (`zsh`), hostname, current working directory\n- **Working directory listing**: top-level entries, with `.gitignore` respected when inside a Git repo\n- **Git status**: branch + counts (`M=3 ?=1`), no file paths\n\n**Never sent**: file contents, env vars, recursive listings, command history, or git diffs.\n\n### Sensitive filenames\n\nFilenames that look like credentials are redacted to `[redacted]` before being sent. The list covers dotenv files, PEM/key/keystore files, SSH keys, cloud credential dirs (`.aws`, `.gcp`, `.azure`, `.kube`), shell history, Terraform state, WireGuard configs, OpenVPN profiles, and similar (see [`internal/runner/context.go`](internal/runner/context.go) for the full list).\n\nTo disable redaction, edit `~/.config/ai/config.yaml`:\n\n```yaml\nredact_secrets: false\n```\n\n## Configuration\n\n`~/.config/ai/config.yaml`:\n\n```yaml\napi_key: sk-or-...                    # plaintext OpenRouter key, OR…\nop_ref: op://Vault/Item/field         # 1Password secret reference (resolved via `op read`)\nmodel: anthropic/claude-haiku-4.5\nredact_secrets: true                  # default; set false to send raw filenames\n```\n\n`$OPENROUTER_API_KEY` always takes precedence over the file.\n\n## Releasing\n\nTagged pushes (`v*`) trigger `.github/workflows/release.yml`, which runs GoReleaser to build binaries for darwin/linux × amd64/arm64, publish a GitHub Release with checksums, and update the `hra42/homebrew-tap` formula.\n\n```sh\ngit tag v0.1.4\ngit push origin v0.1.4\n```\n\nA `HOMEBREW_TAP_GITHUB_TOKEN` secret (PAT with `repo` scope on `hra42/homebrew-tap`) must be configured in the repo's Actions secrets.\n\n## License\n\n[Unlicense](LICENSE) — public domain.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhra42%2Fai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhra42%2Fai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhra42%2Fai/lists"}