{"id":47068025,"url":"https://github.com/cheikh2shift/godex","last_synced_at":"2026-04-12T14:03:01.262Z","repository":{"id":343856836,"uuid":"1177020046","full_name":"cheikh2shift/godex","owner":"cheikh2shift","description":"AI coding agent. ","archived":false,"fork":false,"pushed_at":"2026-04-02T23:32:12.000Z","size":20606,"stargazers_count":23,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T00:39:20.868Z","etag":null,"topics":["agentic-ai","agents","ai","codex","codex-cli","hermes","llm","orchestrator"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cheikh2shift.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-03-09T16:02:02.000Z","updated_at":"2026-04-02T23:32:17.000Z","dependencies_parsed_at":"2026-04-02T12:09:29.226Z","dependency_job_id":null,"html_url":"https://github.com/cheikh2shift/godex","commit_stats":null,"previous_names":["cheikh2shift/godex"],"tags_count":88,"template":false,"template_full_name":null,"purl":"pkg:github/cheikh2shift/godex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheikh2shift%2Fgodex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheikh2shift%2Fgodex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheikh2shift%2Fgodex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheikh2shift%2Fgodex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cheikh2shift","download_url":"https://codeload.github.com/cheikh2shift/godex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheikh2shift%2Fgodex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31579058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"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":["agentic-ai","agents","ai","codex","codex-cli","hermes","llm","orchestrator"],"created_at":"2026-03-12T05:20:22.902Z","updated_at":"2026-04-09T00:02:01.830Z","avatar_url":"https://github.com/cheikh2shift.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![godex-ai-agent](https://snapcraft.io/godex-ai-agent/badge.svg)](https://snapcraft.io/godex-ai-agent)\n[![godex-ai-agent](https://snapcraft.io/godex-ai-agent/trending.svg?name=0)](https://snapcraft.io/godex-ai-agent)\n\n# GoDex - AI Agent\n\nGoDex is an AI coding agent that interfaces with Ollama, llama.cpp, Gemini, OpenRouter (and other LLM providers) through a TUI, with built-in MCP support.\n\nOrchestration and parallel tasks? open another terminal tab and start a new instance of `godex`.\n\n## Requirements\n\n- **Go 1.25.7+** - Build from source\n- **Ollama** - For the default LLM backend (or use Gemini, OpenRouter, or llama.cpp)\n\n## Table of Contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [Quick Install](#quick-install-linuxmacos)\n  - [Docker](#quick-install-docker)\n  - [Build from Source](#build-from-source)\n  - [Manual Download](#manual-download)\n- [Setting up providers](#setting-up-providers)\n  - [Ollama Setup](#ollama-setup)\n  - [OpenRouter Setup](#openrouter-setup)\n  - [llama.cpp Setup](#llamacpp-setup)\n- [Configuration](#configuration)\n  - [Quick Setup](#quick-setup)\n  - [Manual Configuration](#manual-configuration)\n  - [Configuration Options](#configuration-options)\n  - [MCP Servers](#mcp-servers)\n  - [Hive Network](#hive-network)\n- [Usage](#usage)\n  - [Shell Completion](#shell-completion)\n  - [Commands in TUI](#commands-in-tui)\n- [Building](#building)\n- [Running Securely with Docker](#running-securely-with-docker)\n- [Troubleshooting](#troubleshooting)\n\n## Installation\n\n### Quick Install (Linux/macOS)\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/cheikh2shift/godex/main/install.sh | sh\n```\n\n### Quick Install (Docker)\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/cheikh2shift/godex/main/install-docker.sh | bash\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/cheikh2shift/godex.git\ncd godex\ngo build -o godex ./cmd/godex\nsudo mv godex /usr/local/bin/\n```\n\n-------------------------------------------------------------\n\n## Setting up providers\n\n### Ollama Setup\n\n1. **Install Ollama**: Follow instructions at https://github.com/ollama/ollama\n\n2. **Start Ollama server**:\n   ```bash\n   ollama serve\n   ```\n\n3. **Pull a model** (recommended: nemotron-3-super:cloud or minimax-m2.7:cloud):\n   ```bash\n   ollama pull nemotron-3-super:cloud\n   # or\n   ollama pull minimax-m2.7:cloud\n   ```\n\n4. **Verify Ollama is running**:\n   ```bash\n   curl http://localhost:11434\n   ```\n\n### OpenRouter Setup\n\nLaunch Godex and choose `oauth` as the form of authentication to automatically obtain an API key or:\n\n1. **Get an API key**: Sign up at https://openrouter.ai/keys\n\n2. **Set the environment variable**:\n   ```bash\n   export OPENROUTER_API_KEY=sk-or-v1-...\n   ```\n\n3. **Run the wizard** to configure:\n   ```bash\n   godex --wizard\n   ```\n   Select `openrouter` as the provider type and choose from 100+ available models.\n\n### llama.cpp Setup\n\n1. **Install llama.cpp**: Download from https://github.com/ggerganov/llama.cpp/releases or build from source\n\n2. **Ensure llama-server is in your PATH**: The binary should be named `llama-server` and accessible from command line\n\n3. **Run the wizard** to configure:\n   ```bash\n   godex --wizard\n   ```\n   Select `llama.cpp` as the provider type. GoDex will automatically download models from Hugging Face or use local GGUF files.\n\n4. **Using an external llama-server** (optional):\n   ```bash\n   # Start llama-server manually with jinja support for function calling\n   llama-server -m models/your-model.gguf -fa -c 8192 --jinja\n   \n   # Connect godex to it\n   godex --llama-server http://localhost:8080\n   ```\n\n## Configuration\n\nGoDex reads provider configuration from `~/.godex/providers.yaml`.\n\n\n### Manual Download\n\nDownload from [GitHub Releases](https://github.com/cheikh2shift/godex/releases):\n\n| OS | Architecture | File |\n|----|-------------|------|\n| Linux | AMD64 | `godex-linux-amd64` |\n| Linux | ARM64 | `godex-linux-arm64` |\n| macOS | AMD64 | `godex-darwin-amd64` |\n| macOS | ARM64 | `godex-darwin-arm64` |\n| Windows | AMD64 | `godex-windows-amd64.exe` |\n\nExample:\n\n**Linux (AMD64):**\n```bash\ncurl -L -o godex https://github.com/cheikh2shift/godex/releases/latest/download/godex-linux-amd64\nchmod +x godex\nsudo mv godex /usr/local/bin/\n```\n\n**macOS (Intel):**\n```bash\ncurl -L -o godex https://github.com/cheikh2shift/godex/releases/latest/download/godex-darwin-amd64\nchmod +x godex\nsudo mv godex /usr/local/bin/\n```\n\n**macOS (Apple Silicon):**\n```bash\ncurl -L -o godex https://github.com/cheikh2shift/godex/releases/latest/download/godex-darwin-arm64\nchmod +x godex\nsudo mv godex /usr/local/bin/\n```\n\n### Quick Setup\n\nRun the wizard to generate the config:\n```bash\ngodex --wizard\n```\n\n### Manual Configuration\n\nCreate `~/.godex/providers.yaml`:\n\n```yaml\nproviders:\n  - name: ollama\n    type: ollama\n    endpoint: http://localhost:11434\n    model: minimax-m2.5:cloud\n    description: Ollama with codeqwen\n    temperature: 0.2\n    mcp_servers:\n      - name: filesystem # enable file exploring\n      - name: bash # enable command execution\n\ndefault_provider: ollama\n```\n\nDocker note: from inside the GoDex container, use `http://ollama-proxy:11434` to reach the nginx proxy, or `http://host.docker.internal:11434` to reach a host Ollama instance.\n\n### Configuration Options\n\n| Field | Description |\n|-------|-------------|\n| `name` | Provider identifier |\n| `type` | Provider type: `ollama`, `llama.cpp`, `gemini` or `openrouter` |\n| `endpoint` | Base URL for provider (Ollama: `http://localhost:11434`, llama.cpp: `http://localhost:8080`, OpenRouter: `https://openrouter.ai/api/v1`) |\n| `model` | Model name (e.g., `nemotron-3-super:cloud`, `codellama`, `minimax-m2.7:cloud` |\n| `description` | Human-readable description |\n| `temperature` | LLM temperature (0.0-1.0) |\n| `max_tool_rounds` | Max tool call rounds (default: 10) |\n| `tool_timeout` | Tool execution timeout in seconds (default: 180) |\n| `api_key_env` | Environment variable for API key (Gemini/OpenRouter) |\n| `api_key` | Direct API key (not recommended) |\n| `mcp_servers` | List of MCP servers to enable |\n| `context_limit` | Context window size in tokens (auto-detected for OpenRouter) |\n\n### MCP Servers\n\nGoDex includes built-in MCP servers:\n\n| Server | Description |\n|--------|-------------|\n| `filesystem` | Read, write, list directories, create/delete files |\n| `bash` | Run shell commands, Python, Node.js |\n| `webscraper` | Fetch URLs with JavaScript rendering, search HTML, extract links |\n\nFor detailed MCP configuration including external servers, see [MCP.md](MCP.md).\n\n### Hive Network\n\nGoDex supports a Hive network mode where multiple instances can delegate tasks to each other. See [HIVE.md](HIVE.md) for details.\n\n#### Adding Allowed Paths\n\nBy default, MCP servers only allow access to the current working directory. Add more allowed paths:\n\n```yaml\nmcp_servers:\n  - name: filesystem\n    allowed_paths:\n      - /home/user/project1\n      - /home/user/project2\n  - name: bash\n    allowed_paths:\n      - /home/user/project1\n  - name: webscraper\n    allowed_urls:\n      - https://example.com\n      - https://docs.example.com\n```\n\n## Usage\n\n### Quick Install\n\n```bash\n# Build from source (recommended)\ngo build -o godex ./cmd/godex\nsudo mv godex /usr/local/bin/\n\n# Or use install script (requires release)\ncurl -sSL https://raw.githubusercontent.com/cheikh2shift/godex/main/install.sh | sh\n```\n\n### Run\n\n```bash\n# Run the TUI (uses default provider from config)\ngodex\n\n# Run with custom config file\ngodex --config /path/to/providers.yaml\n\n# Run with specific provider (must exist in config)\ngodex --provider ollama\n\n# Run with custom config and specific provider\ngodex --config /path/to/providers.yaml --provider gemini\n\n# Run a single prompt (non-interactive)\ngodex --prompt \"list files in current directory\"\n\n# Run wizard to create config\ngodex --wizard\n```\n\n### Shell Completion\n\nEnable tab completion for `godex` commands and provider names:\n\n**Bash** (add to `~/.bashrc`):\n```bash\nsource \u003c(godex --completion bash)\n```\n\n**Zsh** (add to `~/.zshrc`):\n```bash\nsource \u003c(godex --completion zsh)\n```\n\n**Fish**:\n```bash\ngodex --completion fish | source\n```\n\nAfter sourcing, pressing Tab will show:\n- All available flags with descriptions\n- Provider names when using `--provider`\n- File paths when using `--config`\n\n### Commands in TUI\n\n- `/help` - Show help\n- `/paths` - Show allowed MCP paths\n- `/add-path \u003cfilesys|url\u003e \u003cpath\u003e` - Add allowed path\n- `/tools` - Show available MCP tools\n- `/commit \u003cmessage\u003e` - Save current chat history (CVC)\n- `/commit-search \u003cquery\u003e` - Search commits (CVC)\n- `/commit-pull \u003cref\u003e` - Restore a commit (CVC)\n- `/commit-merge \u003cref\u003e` - Merge a commit into current state (CVC)\n- `/exit` or `/quit` - Exit\n- Up/Down arrows - Command history\n- Tab - Autocomplete `/` commands\n\nGoDex includes CVC (Chat Version Control) for saving and restoring conversation state. See [CVC.md](CVC.md).\n\n### Example Session\n\n```\n$ godex\nGoDex - Connected to ollama (codeqwen)\nMCP Servers: 2\n\n\u003e list files in this directory\n[tool call: list_directory]\n...\n```\n\n## Building\n\n```bash\ngo build -o godex ./cmd/godex\n./godex\n```\n\n## Running Securely with Docker\n\nGoDex can be run in an isolated Docker container with a pre-configured sandbox environment containing common tools (Python, Node.js, Go, Rust, etc.).\n\n### Quick Install\n\n### Why Use Docker?\n\nRunning GoDex in Docker provides:\n- **Isolation** - GoDex operates only within the mounted workspace directory\n- **No host pollution** - Tools and changes stay contained\n- **Consistent environment** - Same tools available regardless of host system\n- **Safety** - Test configurations without risking your host system\n\n\n### Usage\n\n1. **First run** - The container will launch the wizard to configure your provider:\n   ```bash\n   WORKSPACE_DIR=\"$PWD\" docker compose -f $HOME/godex/docker-compose.yml up\n   ```\n   Configure your Ollama/OpenRouter/etc. settings when prompted.\n   If the screen looks empty after attaching, press Enter to trigger TUI redraw.\n   If using Ollama on the host with the nginx proxy, make sure Ollama listens on `0.0.0.0:11434` (not just `127.0.0.1`), e.g. `OLLAMA_HOST=0.0.0.0:11434 ollama serve`.\n\n#### Ollama Host Firewall (Optional)\n\nIf you want Ollama bound to `0.0.0.0` use:\n```bash\nsudo mkdir -p /etc/systemd/system/ollama.service.d\nsudo tee /etc/systemd/system/ollama.service.d/override.conf \u003e/dev/null \u003c\u003c'EOF'\n[Service]\nEnvironment=\"OLLAMA_HOST=0.0.0.0:11434\"\nEOF\nsudo systemctl daemon-reload\nsudo systemctl restart ollama\n\n```\n\n2. **Subsequent runs** - Your config is persisted in `$HOME/.godex`:\n   ```bash\n   WORKSPACE_DIR=\"$PWD\" docker compose -f $HOME/godex/docker-compose.yml up -d \u0026\u0026 docket attach godex\n   ```\n\n**Note:** `WORKSPACE_DIR` controls which host directory is mounted at `/workspace` in the container. Set it to the directory you want GoDex to operate in (defaults to the compose file directory if unset).\n\n3. **Edit provider config in `$HOME/.godex`**:\n   ```bash\n   nano $HOME/.godex/providers.yaml\n   vi $HOME/.godex/providers.yaml\n   vim $HOME/.godex/providers.yaml\n   ```\n\n### Included Tools in Docker\n\nThe sandbox includes:\n- Python 3, pip, pytest, black, flake8\n- Node.js, npm\n- Go, Rust\n- Git, curl, wget\n- Build tools: make, cmake, gcc, g++\n- Utilities: htop, tree, jq, ripgrep, fd, fzf, vim, nano\n\n### Security Notes\n\n- GoDex can only access files within the `./workspace` directory (read-write)\n- Container runs as non-root user (set via `USER_ID`/`GROUP_ID`, defaults to `1000:1000`)\n- Most Linux capabilities dropped; only `NET_RAW` and `NET_BIND_SERVICE` allowed\n- No new privileges allowed\n- `/tmp` and `/run` use tmpfs (memory-only, non-persistent)\n- No explicit process/file limits (inherits host defaults)\n- Network isolated via nginx proxy (host port `11435` forwards to `ollama-proxy:11434`, which proxies to host `11434`)\n- Provider credentials are stored in `$HOME/.godex`\n- Use `docker compose -f $HOME/godex/docker-compose.yml down -v` to completely remove all data\n\n## Troubleshooting\n\n### Ollama Model Not Found\n\nIf you get an error like `{\"error\":\"model 'qwen3-coder-next:cloud' not found\"}`, it means the model hasn't been pulled yet. Run:\n\n```bash\nollama pull \u003cmodel-name\u003e\n```\n\nThen test it works with:\n\n```bash\nollama run \u003cmodel-name\u003e\n```\n\n### Ollama Not Running\n\nMake sure Ollama is running in the background. You can start it with:\n\n```bash\nollama serve\n```\n\n### Connection Issues\n\nIf GoDex can't connect to Ollama, check that the Ollama API is accessible at `http://localhost:11434`.\n\n\n\n---\n\nFor developers: [DEV.md](DEV.md) - Guide to adding new MCP servers and providers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheikh2shift%2Fgodex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheikh2shift%2Fgodex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheikh2shift%2Fgodex/lists"}