https://github.com/kcaldas/genie
🧞 Powerful AI assistant for your command line - Built with Go and Gemini AI
https://github.com/kcaldas/genie
ai assistant cli coding-assistant gemini golang terminal tui
Last synced: 14 days ago
JSON representation
🧞 Powerful AI assistant for your command line - Built with Go and Gemini AI
- Host: GitHub
- URL: https://github.com/kcaldas/genie
- Owner: kcaldas
- License: mit
- Created: 2025-06-16T03:04:02.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-03-11T05:23:33.000Z (16 days ago)
- Last Synced: 2026-03-11T10:53:35.492Z (16 days ago)
- Topics: ai, assistant, cli, coding-assistant, gemini, golang, terminal, tui
- Language: Go
- Size: 2.23 MB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# 🧞 Genie - Powerful AI for Your Command Line
[](https://golang.org)
[](https://opensource.org/licenses/MIT)
[](https://github.com/kcaldas/genie/pkgs/container/genie)
[](https://github.com/kcaldas/genie/releases)
Transform your terminal into an AI-powered workspace. Born from a developer's need for control and transparency in AI assistance.
Quick demo:
[](https://asciinema.org/a/asMYIL7iVrpEck2CeLAI3sPqN)
Theming demo:
[](https://asciinema.org/a/RlX6vOghWR2ZIaG0gevAG5Cvp)
## 🚀 Quick Start
### Installation
#### macOS (Homebrew)
```bash
brew tap kcaldas/genie
brew install genie
```
#### Direct Download
```bash
# Download latest release
curl -L https://github.com/kcaldas/genie/releases/latest/download/genie_$(uname -s)_$(uname -m).tar.gz | tar xz
sudo mv genie /usr/local/bin/
```
#### Docker
```bash
docker run --rm -it ghcr.io/kcaldas/genie:latest
```
#### Build from Source
```bash
go install github.com/kcaldas/genie/cmd/genie@latest
```
### Configuration
Genie ships with Gemini enabled by default. To get started:
1. Generate a key from [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Set it as an environment variable:
```bash
export GEMINI_API_KEY="YOUR_API_KEY"
genie ask "hello world" # CLI mode
git diff | genie ask "commit msg?" # Unix pipes
genie # Interactive TUI mode
```
> **💡 Tip:** The Gemini API provides 100 free requests per day with Gemini 2.5 Pro. Upgrade to a paid plan for higher rate limits.
Prefer OpenAI? Switch providers with two environment variables:
```bash
export GENIE_LLM_PROVIDER="openai"
export OPENAI_API_KEY="sk-your-api-key"
genie ask "summarize README.md"
```
Optionally set `OPENAI_BASE_URL` or `OPENAI_ORG_ID` if you use a custom endpoint.
Prefer Anthropic? Use the Claude models instead:
```bash
export GENIE_LLM_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="sk-ant-api-key"
genie ask "explain retrieval augmented generation"
```
Set `ANTHROPIC_SHOW_THINKING=true` if you want Claude's thinking blocks streamed as notifications.
**📖 Full setup guide:** [docs/INSTALLATION.md](docs/INSTALLATION.md)
## 🎭 Personas
Genie supports different personas for specialized tasks:
```bash
# Use specific personas
genie --persona engineer ask "review this code"
genie --persona product-owner ask "plan this feature"
```
Each persona can pin its own `model_name` and `llm_provider` inside `prompt.yaml`, while `GENIE_MODEL_NAME` and `GENIE_LLM_PROVIDER` remain global fallbacks.
**📖 Learn more:** [docs/personas.md](docs/personas.md)
## 💡 Philosophy
Inspired by [Lazygit](https://github.com/jesseduffield/lazygit), [Claude Code](https://claude.ai/code), and [Aider](https://github.com/paul-gauthier/aider), and built for the Unix philosophy: composable, transparent, and adaptable.
**Core beliefs:**
- **Give you control** - Understand what's happening, not just trust a black box, and is infinitely hackable
- **Integrate naturally** - Work with your existing tools, don't replace them
- **Respect the terminal** - Embrace the power and flexibility of the command line
- **Stay composable** - Pipe, redirect, script, and automate freely
Whether you're coding, managing projects, taking notes, or automating workflows, Genie adapts to your needs.
## 📚 Documentation
- **[Installation & Setup](docs/INSTALLATION.md)** - Complete installation guide
- **[TUI Guide](docs/TUI.md)** - Interactive interface features
- **[CLI Usage](docs/CLI.md)** - Command line examples
- **[Configuration](docs/CONFIGURATION.md)** - Customization options
- **[Personas](docs/personas.md)** - AI personality system
- **[Docker Usage](docs/DOCKER.md)** - Container setup
- **[Architecture](docs/ARCHITECTURE.md)** - How Genie works
- **[Contributing](CONTRIBUTING.md)** - Join the project
## 🔗 Ecosystem
- [kcaldas/genie.nvim](https://github.com/kcaldas/genie.nvim) - Neovim companion plugin
## 🙏 Acknowledgments
Built with [Google Gemini AI](https://ai.google.dev/) • [gocui](https://github.com/awesome-gocui/gocui) • [GoReleaser](https://goreleaser.com/)
---
Made with ❤️ for developers who love the command line