{"id":45663046,"url":"https://github.com/hongymagic/q","last_synced_at":"2026-04-28T02:04:54.761Z","repository":{"id":340308772,"uuid":"1165417797","full_name":"hongymagic/q","owner":"hongymagic","description":"Quick AI interactions in the terminal - Full shazzy AI created tool","archived":false,"fork":false,"pushed_at":"2026-03-29T00:31:38.000Z","size":469,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T03:11:56.468Z","etag":null,"topics":["ai-assistant","cursor","experimental","jules","opencode"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/hongymagic.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-24T06:24:40.000Z","updated_at":"2026-03-28T00:30:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hongymagic/q","commit_stats":null,"previous_names":["hongymagic/q"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/hongymagic/q","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongymagic%2Fq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongymagic%2Fq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongymagic%2Fq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongymagic%2Fq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hongymagic","download_url":"https://codeload.github.com/hongymagic/q/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongymagic%2Fq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31313178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["ai-assistant","cursor","experimental","jules","opencode"],"created_at":"2026-02-24T09:24:20.586Z","updated_at":"2026-04-02T18:41:14.576Z","avatar_url":"https://github.com/hongymagic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# q — Quick AI Answers from the Command Line\n\n[![CI](https://github.com/hongymagic/q/actions/workflows/ci.yml/badge.svg)](https://github.com/hongymagic/q/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@hongymagic/q.svg)](https://www.npmjs.com/package/@hongymagic/q)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA fast, minimal CLI for getting AI answers directly in your terminal.\n\nWhen running in an interactive terminal, `q` shows a small ASCII loading indicator on stderr while it waits for the first response text.\n\n## Installation\n\n```bash\nnpm install -g @hongymagic/q\n```\n\nOr download a standalone binary from the [releases page](https://github.com/hongymagic/q/releases).\n\nOr build from source with [Bun](https://bun.sh):\n\n```bash\ngit clone https://github.com/hongymagic/q.git \u0026\u0026 cd q\nbun install \u0026\u0026 bun run build\n```\n\n## Setup\n\n`q` works without a config file.\n\n1. **Free local setup with Ollama**\n\n```bash\nollama pull gemma3\nq --provider ollama --model gemma3 explain this stack trace\n```\n\n2. **Free cloud setup with Gemini**\n\n```bash\nexport GEMINI_API_KEY=\"your-key-here\"\nq explain rust lifetimes\n```\n\n3. **Optional: create a pinned config**\n\n```bash\nq config init\n```\n\n`q` auto-detects common provider keys (`GEMINI_API_KEY`, `GROQ_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) and falls back to local Ollama when available.\n\n## Usage\n\n```bash\nq how do I restart docker\nGEMINI_API_KEY=\"your-key\" q explain closures in javascript\nq --copy what is a kubernetes pod\nq --provider ollama --model gemma3 explain this error\n```\n\n### Piping Content\n\nPipe content as context for your question:\n\n```bash\ncat error.log | q \"what's wrong here?\"\ngit diff | q \"summarise these changes\"\n```\n\nOr pipe the query itself:\n\n```bash\necho \"how do I restart docker\" | q\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `-p, --provider \u003cname\u003e` | Override the default provider |\n| `-m, --model \u003cid\u003e` | Override the default model |\n| `--mode \u003cmode\u003e` | Output mode: `command` (default) or `explain` |\n| `--copy` | Copy answer to clipboard |\n| `--no-copy` | Disable copy (overrides config) |\n| `--debug` | Enable debug logging to stderr |\n| `-h, --help` | Show help message |\n| `-v, --version` | Show version |\n\n### Output Modes\n\nBy default, `q` returns terse, copy/paste-ready commands. Use `--mode explain` for detailed explanations:\n\n```bash\nq how do I restart docker               # Returns the command(s)\nq --mode explain how do I restart docker # Returns a detailed explanation\n```\n\n### Commands\n\n```bash\nq config path    # Print config file path\nq config init    # Create optional config file\nq config doctor  # Diagnose config and setup issues\nq providers      # List available providers + model and credential status\n```\n\n## Configuration\n\nConfig is optional. `q` starts with built-in provider presets and per-provider defaults, then applies overrides (later overrides earlier):\n\n1. Built-in defaults (`google`, `groq`, `anthropic`, `openai`, `ollama`, `azure`, `bedrock`)\n2. `$XDG_CONFIG_HOME/q/config.toml` (or `~/.config/q/config.toml`)\n3. `./config.toml` (project-specific)\n4. Environment: `Q_PROVIDER`, `Q_MODEL`, `Q_COPY`\n5. CLI flags: `--provider`, `--model`\n\nEach provider can specify its own default `model`, which takes precedence over `default.model` but is overridden by `Q_MODEL` or `--model`:\n\n```toml\n[default]\nprovider = \"google\"\n# model = \"gemini-2.5-flash\"         # Optional global default\n\n[providers.google]\ntype = \"google\"\napi_key_env = \"GEMINI_API_KEY\"\nmodel = \"gemini-2.5-flash\"           # Optional per-provider default\n```\n\nSee [config.example.toml](config.example.toml) for all options.\n\n### Free Setup Options\n\n| Option | Cost | What you need | Notes |\n|------|------|---------------|-------|\n| `ollama` | Free local | Ollama installed and a local model | Best zero-key/offline option |\n| `google` | Free tier | `GEMINI_API_KEY` (or `GOOGLE_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`) | Best free cloud default |\n| `groq` | Free tier | `GROQ_API_KEY` | Fast free cloud fallback |\n\n### Provider Types\n\n| Type | Built in | Description |\n|------|----------|-------------|\n| `google` | Yes | Google Gemini API |\n| `groq` | Yes | Groq (ultra-fast open models) |\n| `ollama` | Yes | Local Ollama instance |\n| `anthropic` | Yes | Anthropic Claude API |\n| `openai` | Yes | OpenAI API |\n| `azure` | Yes | Azure OpenAI deployments |\n| `bedrock` | Yes | AWS Bedrock (Claude, Titan, Llama) |\n| `openai_compatible` | No | Any OpenAI-compatible API (needs `base_url`) |\n| `portkey` | No | Portkey AI Gateway (needs `base_url` and `provider_slug`) |\n\n### Portkey Gateway Setup\n\n[Portkey](https://portkey.ai) is an AI gateway that provides unified access to multiple LLM providers with features like load balancing, caching, and observability. Use the `portkey` provider type for self-hosted or cloud deployments.\n\n**Self-hosted gateway:**\n\n```toml\n[default]\nprovider = \"portkey_internal\"\nmodel = \"us.anthropic.claude-sonnet-4-20250514-v1:0\"\n\n[providers.portkey_internal]\ntype = \"portkey\"\nbase_url = \"https://your-portkey-gateway.internal/v1\"\nprovider_slug = \"@your-org/bedrock-provider\"\napi_key_env = \"PORTKEY_API_KEY\"\nprovider_api_key_env = \"PROVIDER_API_KEY\"\n```\n\n**Configuration options:**\n\n| Field | Description |\n|-------|-------------|\n| `base_url` | Your Portkey gateway URL |\n| `provider_slug` | Provider identifier (maps to `x-portkey-provider` header) |\n| `api_key_env` | Environment variable for Portkey API key (maps to `x-portkey-api-key` header) |\n| `provider_api_key_env` | Environment variable for underlying provider's API key (maps to `Authorization` header) |\n| `headers` | Additional custom headers (supports env var interpolation for allowlisted vars) |\n\n**Environment variables:**\n\n```bash\nexport PORTKEY_API_KEY=\"your-portkey-key\"\nexport PROVIDER_API_KEY=\"your-provider-key\"\n```\n\n## Self-Evolving System\n\n`q` includes an autonomous improvement system powered by [GitHub Agentic Workflows](https://github.github.io/gh-aw/). AI agents continuously scan, assess, and improve the codebase across multiple dimensions — security, features, maintenance, performance, test coverage, and usability.\n\n| Agent | Schedule | Purpose |\n|-------|----------|---------|\n| Security Daily | Daily | Scan and fix security vulnerabilities |\n| Feature Daily | Daily | Detect and implement feature gaps |\n| Maintenance Daily | Daily | Fix dead code, test gaps, docs drift |\n| Self Improve Weekly | Monday | Retrospective on PR quality patterns |\n| Performance Weekly | Tuesday | Binary size, speed, memory optimisation |\n| Coverage Weekly | Wednesday | Expand test coverage |\n| Usability Weekly | Thursday | CLI UX, error messages, help text |\n| Self Evolve Fortnightly | 1st \u0026 15th | Meta-agent: improve the agents themselves |\n\nAll agent PRs are created as drafts and require human approval to merge. The system is governed by `.github/CONSTITUTION.md` which defines immutable safety rules. All autonomous changes are tracked in `.github/EVOLUTION.md`.\n\n## Troubleshooting\n\n**\"Setup required\" error:**\n\nUse one of these quick starts:\n\n```bash\nexport GEMINI_API_KEY=\"your-key-here\"\nq explain kubernetes pods\n```\n\n```bash\nq --provider ollama --model gemma3 explain kubernetes pods\n```\n\nOr create a config file with `q config init`.\n\n**\"Missing API key\" error:**\n\nEnsure your API key environment variable is set:\n\n```bash\nexport GEMINI_API_KEY=\"your-key-here\"\n```\n\n**Diagnose config issues:**\n\nRun `q config doctor` to check config files, environment overrides, built-in defaults, and provider health at a glance.\n\n**Failure logs:**\n\nMost non-usage failures print a short error plus `Full log: \u003cpath\u003e` on stderr. Logs are written to your platform log directory, for example `~/.local/state/q/errors` on Linux.\n\nIn an interactive terminal, query failures also offer quick recovery options: press `r` to retry, `Enter` to print the full log, or `q`/`Esc` to exit.\n\n**Debug mode:**\n\nUse `--debug` to keep detailed diagnostics on stderr while still writing the full failure log:\n\n```bash\nq --debug \"how do I list docker containers\"\n```\n\n**Piped content not working:**\n\nEnsure you're piping content correctly. The query should be in arguments:\n\n```bash\ncat file.txt | q \"explain this\"   # Correct\ncat file.txt | q                   # Uses stdin as query (no context)\n```\n\n## Licence\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongymagic%2Fq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhongymagic%2Fq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongymagic%2Fq/lists"}