{"id":33065312,"url":"https://github.com/raphaelmansuy/adk-code","last_synced_at":"2025-11-19T16:01:49.816Z","repository":{"id":324073190,"uuid":"1095853828","full_name":"raphaelmansuy/adk-code","owner":"raphaelmansuy","description":"adk-code 🚀 AI coding assistant for your terminal. Powered by Google's ADK framework with multi-model support (Gemini 🔷, OpenAI 🟢, Vertex AI ☁️).  First ADK code agent in Go! 🎯","archived":false,"fork":false,"pushed_at":"2025-11-14T07:13:59.000Z","size":111330,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-14T07:25:03.160Z","etag":null,"topics":["adk","google"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raphaelmansuy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-11-13T15:51:49.000Z","updated_at":"2025-11-14T07:13:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raphaelmansuy/adk-code","commit_stats":null,"previous_names":["raphaelmansuy/adk-code"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/raphaelmansuy/adk-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fadk-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fadk-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fadk-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fadk-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raphaelmansuy","download_url":"https://codeload.github.com/raphaelmansuy/adk-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fadk-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284893575,"owners_count":27080531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-17T02:00:06.431Z","response_time":55,"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":["adk","google"],"created_at":"2025-11-14T07:07:46.095Z","updated_at":"2025-11-17T14:00:50.141Z","avatar_url":"https://github.com/raphaelmansuy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adk-code\n\n\u003e **An intelligent CLI coding assistant powered by Google's ADK framework**\n\n[![Go](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat-square\u0026logo=go)](https://golang.org)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/raphaelmansuy/adk-code?style=flat-square)](https://github.com/raphaelmansuy/adk-code)\n\n\n## What is adk-code?\n\n`adk-code` is a **multi-model AI coding assistant** that runs directly in your terminal. Ask natural language questions about your code—it reads files, executes commands, makes edits, and runs searches autonomously.\n\n### Key Features\n\n- **🤖 Multi-Model Support**: Seamlessly switch between Gemini, OpenAI, and Vertex AI\n- **🛠️ 30+ Built-in Tools**: File operations, code editing, execution, searching, and more\n- **🔌 MCP Integration**: Unlimited extensibility via Model Context Protocol\n- **💾 Session Persistence**: Maintain context across conversations with automatic history\n- **⚡ Streaming Responses**: Real-time output as the model thinks and executes\n- **🎨 Beautiful Terminal UI**: Rich formatting, colors, and interactive displays\n- **📦 Zero External Dependencies**: No Langchain, Claude Code, or Cline baggage\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone and build\ngit clone https://github.com/raphaelmansuy/adk-code.git\ncd adk-code/adk-code\nmake build\n\n# Binary is now at ../bin/adk-code\n```\n\n### 1-Minute Setup\n\n```bash\n# Set your API key\nexport GOOGLE_API_KEY=your-key-here\n\n# Run adk-code\n../bin/adk-code\n```\n\nThat's it! You're ready to ask questions about your code.\n\n### Examples\n\n```bash\n# Interactive mode (default)\n❯ How do I add error handling to ReadFile?\n[adk-code reads files, analyzes, and suggests changes]\n\n❯ Create a CLI parser for flags\n[adk-code implements, tests, and explains]\n\n# Session mode\n❯ adk-code --session my-project --model gpt-4o\n\n# Batch mode\n❯ echo \"Write a test for userAuth()\" | adk-code\n```\n\n## 🎯 Use Cases\n\n| Use Case | Benefit |\n|----------|---------|\n| **Code Review** | Understand complex codebases quickly |\n| **Bug Fixes** | Trace errors and implement solutions |\n| **Refactoring** | Improve code quality with AI guidance |\n| **Documentation** | Generate docs and comments |\n| **Testing** | Write and run test suites |\n| **Learning** | Study patterns and best practices |\n\n## 🏗️ Architecture at a Glance\n\n```\n┌─────────────────────────────────┐\n│     User Terminal (REPL)        │\n└────────────┬────────────────────┘\n             │\n┌────────────▼────────────────────┐\n│   Agent Loop (ADK Framework)    │\n│  ┌──────────────────────────┐   │\n│  │ 1. Call LLM with context │   │\n│  │ 2. Parse tool calls      │   │\n│  │ 3. Execute tools         │   │\n│  │ 4. Append results        │   │\n│  │ 5. Loop until complete   │   │\n│  └──────────────────────────┘   │\n└────────────┬────────────────────┘\n             │\n    ┌────────┴────────┬──────────┐\n    ▼                 ▼          ▼\n┌────────────┐  ┌─────────┐  ┌──────────┐\n│ 30+ Tools  │  │LLM APIs │  │ Display  │\n├────────────┤  ├─────────┤  ├──────────┤\n│ File Ops   │  │ Gemini  │  │ Rich UI  │\n│ Execution  │  │ OpenAI  │  │ Colors   │\n│ Search     │  │ Vertex  │  │ Markdown │\n└────────────┘  └─────────┘  └──────────┘\n```\n\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.\n\n## 📚 Documentation\n\n- **[QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)** — Daily commands \u0026 flags (2 min)\n- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** — System design \u0026 components (15 min)\n- **[TOOL_DEVELOPMENT.md](docs/TOOL_DEVELOPMENT.md)** — Build your own tools (20 min)\n- **[docs/](docs/)** — Complete documentation suite\n\n## 💻 Requirements\n\n- **Go 1.24+**\n- One API key:\n  - `GOOGLE_API_KEY` (Gemini - free tier available)\n  - `OPENAI_API_KEY` (OpenAI)\n  - GCP project (Vertex AI)\n\n## 🚀 Getting Started\n\n### Option 1: Gemini (Recommended)\n\nFree tier, fastest setup:\n\n```bash\nexport GOOGLE_API_KEY=your-key\ncd adk-code \u0026\u0026 make run\n```\n\n### Option 2: OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-...\ncd adk-code \u0026\u0026 make run -- --model gpt-4o\n```\n\n### Option 3: Vertex AI (GCP)\n\n```bash\nexport GOOGLE_CLOUD_PROJECT=your-project\nexport GOOGLE_CLOUD_LOCATION=us-central1\nexport GOOGLE_GENAI_USE_VERTEXAI=true\ncd adk-code \u0026\u0026 make run\n```\n\n## 🛠️ Development\n\n```bash\ncd adk-code\n\n# Build\nmake build\n\n# Test\nmake test\n\n# Quality checks (required before commit)\nmake check\n\n# Development watch mode\nmake watch\n```\n\n## 🔧 CLI Flags\n\n```bash\n./adk-code --model gemini-2.5-flash           # Specify model\n./adk-code --session my-project               # Named session\n./adk-code --output-format plain              # Output format\n./adk-code --enable-thinking                  # Extended reasoning\n./adk-code --working-directory /path/to/src   # Set working dir\n```\n\nSee [QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) for all flags.\n\n## 🧠 How It Works\n\n1. **You ask a question** in natural language\n2. **Agent receives context** (system prompt, tools, history)\n3. **LLM generates response** with tool calls (read file, run command, etc.)\n4. **Tools execute** and return results\n5. **Agent loops** until response is complete\n6. **Result streams** to your terminal in real-time\n\nExample: \"How many lines in main.go?\"\n\n```\nAgent thinks: \"User wants line count. I'll use count_lines tool.\"\n  ↓\nCalls: count_lines(path=\"main.go\")\n  ↓\nGets: {success: true, total_lines: 140, ...}\n  ↓\nReturns: \"main.go has 140 lines\"\n```\n\n## 🌐 Extensibility\n\n### Add Tools\n\nCreate your own tools without modifying core code. See [TOOL_DEVELOPMENT.md](docs/TOOL_DEVELOPMENT.md).\n\n```go\n// 4-step pattern\ntype MyToolInput struct { Path string }\ntype MyToolOutput struct { Result string }\n\nfunc handler(ctx Context, input MyToolInput) MyToolOutput {\n    // Your logic\n    return MyToolOutput{Result: \"...\"}\n}\n\nfunc init() {\n    // Register automatically\n}\n```\n\n### Connect External Tools (MCP)\n\nUse Model Context Protocol servers instead of building tools:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"github\": {\n        \"type\": \"stdio\",\n        \"command\": \"mcp-server-github\"\n      }\n    }\n  }\n}\n```\n\n## 📊 Performance\n\n| Metric | Value |\n|--------|-------|\n| **Binary Size** | ~15MB (release) |\n| **Startup Time** | \u003c500ms |\n| **Context Window** | Up to 1M tokens (Gemini 2.5 Flash) |\n| **Tool Execution** | \u003c1s typical |\n| **Memory Usage** | ~50MB baseline |\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n\n1. Fork and create a branch\n2. Make changes following Go conventions\n3. Run `make check` before committing\n4. Submit a pull request with description\n\nSee [TOOL_DEVELOPMENT.md](docs/TOOL_DEVELOPMENT.md) for architecture details.\n\n## 📄 License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.\n\n```\nCopyright 2025 adk-code contributors\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n## 🎓 Learning Path\n\n**New to adk-code?**\n\n```\n5 min   → QUICK_REFERENCE.md → Start using\n1 hour  → ARCHITECTURE.md    → Understand design\n3 hours → Full docs          → Contribute\n```\n\n## ❓ FAQ\n\n**Q: What's the difference between adk-code and ChatGPT?**  \nA: adk-code runs in your terminal with direct filesystem access. No copy-pasting code—just ask.\n\n**Q: Can I use this offline?**  \nA: No, it requires an LLM API. But you can use any of 3 providers (Gemini/OpenAI/Vertex).\n\n**Q: Is my code private?**  \nA: Yes, only sent to your chosen API provider. Self-hosted options available on request.\n\n**Q: How much does it cost?**  \nA: Depends on provider. Gemini has a free tier. OpenAI is ~$0.03/1K tokens.\n\n**Q: Can I build custom tools?**  \nA: Yes! Follow the 4-step pattern in TOOL_DEVELOPMENT.md.\n\n## 🚀 What's Next?\n\n- [ ] Add more tool categories (database, API, etc.)\n- [ ] Support for local LLMs\n- [ ] Web UI option\n- [ ] Plugin marketplace\n\n## 💬 Community\n\n- **Issues**: [GitHub Issues](https://github.com/raphaelmansuy/adk-code/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/raphaelmansuy/adk-code/discussions)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## 🙏 Acknowledgments\n\nBuilt on:\n- [Google ADK](https://github.com/googleapis/google-cloud-go) — Agent framework\n- [Charmbracelet](https://github.com/charmbracelet) — Terminal UI\n- [Gemini/OpenAI/Vertex AI](https://ai.google.dev) — LLM APIs\n\n## 📈 Stats\n\n- **~1000 lines** of critical code\n- **30+ tools** across 8 categories\n- **3 LLM backends** supported\n- **100% test coverage** target\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by the adk-code community**\n\n[⭐ Star us on GitHub](https://github.com/raphaelmansuy/adk-code) | [🐛 Report Bug](https://github.com/raphaelmansuy/adk-code/issues) | [💡 Request Feature](https://github.com/raphaelmansuy/adk-code/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelmansuy%2Fadk-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraphaelmansuy%2Fadk-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelmansuy%2Fadk-code/lists"}