{"id":50996400,"url":"https://github.com/jukefr/opencode-smarts","last_synced_at":"2026-06-20T10:01:19.164Z","repository":{"id":354515110,"uuid":"1223665058","full_name":"jukefr/opencode-smarts","owner":"jukefr","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T21:11:23.000Z","size":131,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T14:26:42.330Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/jukefr.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-04-28T14:36:22.000Z","updated_at":"2026-04-28T21:11:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jukefr/opencode-smarts","commit_stats":null,"previous_names":["jukefr/opencode-smarts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jukefr/opencode-smarts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jukefr%2Fopencode-smarts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jukefr%2Fopencode-smarts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jukefr%2Fopencode-smarts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jukefr%2Fopencode-smarts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jukefr","download_url":"https://codeload.github.com/jukefr/opencode-smarts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jukefr%2Fopencode-smarts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34565244,"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-06-20T02:00:06.407Z","response_time":98,"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":[],"created_at":"2026-06-20T10:01:18.389Z","updated_at":"2026-06-20T10:01:19.154Z","avatar_url":"https://github.com/jukefr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode-smarts\n\nMakes [opencode](https://opencode.ai) behave like an autonomous coding assistant — git-aware, task-complete, and optimized for complex workflows.\n\n## What it does\n\nInstalls a global config pack into `~/.config/opencode/` that gives opencode:\n\n- **Behavioral rules** (`AGENTS.md`) — the agent explores before implementing, tracks work with `todowrite`, always creates a git branch before writing code, commits with conventional commits, offers a PR when done, and only stops when tests and linters pass\n- **Auto project detection** (plugin) — on every session start, scans the project for `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`, etc. and creates/updates a project `AGENTS.md` with the detected stack and commands\n- **Auto GPL3 license** (plugin) — on every session start, fetches the GPLv3 text from gnu.org and writes a `LICENSE` file if none exists in the repository\n- **Model recommender** (TUI plugin) — sidebar panel showing the best free and best paid models based on live data from Artificial Analysis, with a 4-hour local cache to avoid rate limits. Score is a composite of coding ability, intelligence, price, and speed\n- **Free OpenRouter models** (plugin) — automatically adds all `:free` OpenRouter models to the model picker, no API key required\n- **Rule reinforcement** (plugin) — re-injects the critical git/test/commit rules into the system prompt on every LLM call and into the compaction prompt, so the agent keeps following them even deep into long sessions\n- **Auto version bump** (plugin) — after every git commit the agent makes, checks the commit message for semantic type (`feat` → minor, `fix`/`perf`/`refactor` → patch, breaking change → major) and automatically bumps the version in `package.json`, `Cargo.toml`, `pyproject.toml`, or a `VERSION` file, then commits the change\n- **Custom primary agent** (`build`) — overrides the default build agent with explicit step-by-step instructions for the full git workflow\n- **Specialized subagents** — `@explorer`, `@planner`, `@reviewer`, `@tester`, `@code-explorer`, `@code-reviewer` that get spawned automatically for parallel work\n- **Slash commands** — `/feature`, `/fix`, `/review`, `/pr`, `/explore`, `/set-aa-key`, `/refresh-models`\n- **Skills** — reusable instruction sets loaded on demand: `feature-build`, `bug-fix`, `smart-commit`, `smart-pr`, `code-review`\n- **Safe permissions** — blocks `rm -rf`, force-push to main, `DROP TABLE/DATABASE` by default\n- **Context7 MCP** — library docs lookup, enabled by default\n- **Engram MCP** — persistent memory across sessions, auto-installed via `install.sh`\n\n## Install\n\n```bash\ngit clone \u003cthis-repo\u003e ~/opencode-smarts\ncd ~/opencode-smarts\nchmod +x install.sh\n./install.sh\n```\n\nRestart opencode after installing.\n\nRe-running `./install.sh` is safe — symlinks are updated and `opencode.json` is merged non-destructively (your existing settings are preserved, new keys are added).\n\n## Usage\n\n### Slash commands\n\n| Command | What it does |\n|---------|-------------|\n| `/feature \u003cdescription\u003e` | Creates a `feature/\u003cslug\u003e` branch, explores, plans, implements, runs tests + lint, commits, offers PR |\n| `/fix \u003cdescription\u003e` | Creates a `fix/\u003cslug\u003e` branch, finds root cause, fixes, verifies, commits, offers PR |\n| `/review` | Reviews all changes on the current branch — correctness, security, quality, test coverage |\n| `/pr` | Commits anything uncommitted + `git push` + `gh pr create` with auto-generated description |\n| `/explore \u003cquestion\u003e` | Spawns `@explorer` to map the codebase and answer the question |\n| `/set-aa-key` | Opens a dialog to enter your Artificial Analysis API key for model recommendations |\n| `/refresh-models` | Force-refreshes model recommendations from Artificial Analysis, bypassing the local cache |\n\n### Natural language requests\n\nYou don't have to use slash commands. Asking normally also triggers the full workflow:\n\n\u003e \"Add pagination to the users list endpoint\"\n\nThe `build` agent will: check git state → create `feature/add-pagination-users-list` → read `AGENTS.md` → explore the codebase → implement → run tests → run linter → commit → ask if you want a PR.\n\n### Subagents\n\nInvoke directly with `@` or they get spawned automatically:\n\n| Agent | Purpose |\n|-------|---------|\n| `@explorer` | Read-only codebase analysis — maps architecture, finds patterns, locates entry points |\n| `@code-explorer` | Stricter read-only analysis — locked to read/glob/grep/lsp only, no web or bash |\n| `@planner` | Designs implementation plan before coding — files to change, order, interfaces, edge cases |\n| `@reviewer` | Code review — correctness, security, quality, test coverage. Never modifies files |\n| `@code-reviewer` | Stricter code reviewer — launches parallel explore tasks, confidence-scored findings |\n| `@tester` | Runs the test suite and explains each failure with a recommended fix |\n| `@feature-dev` | Full 7-phase autonomous feature implementation |\n| `@ralph-loop` | Iterates until a completion promise is satisfied (max 10 iterations) |\n\n### Skills\n\nLoaded on demand by the agent when relevant:\n\n| Skill | When used |\n|-------|----------|\n| `feature-build` | Detailed 9-phase feature build checklist |\n| `bug-fix` | Systematic debugging — reproduce, root cause, fix, verify |\n| `smart-commit` | Generate and create a conventional commit from current changes |\n| `smart-pr` | Push branch and create PR with auto-generated description |\n| `code-review` | Full parallel review across correctness, security, quality, tests |\n\n## Model recommender\n\nThe model recommender sidebar shows 4 models: the 2 best free models and the 2 best paid models, ranked by a composite score (coding ability, intelligence, price efficiency, and speed). Each entry shows the model name, price per 1M tokens, and the composite score.\n\nIt fetches data from the [Artificial Analysis API](https://artificialanalysis.ai) which requires a free API key. OpenRouter availability data is fetched live on each startup with no key required.\n\n### Setup\n\n1. Get a free API key from [artificialanalysis.ai](https://artificialanalysis.ai)\n2. Either set the environment variable: `export AA_API_KEY=your_key_here`\n3. Or use the in-app command: `/set-aa-key` — opens a dialog, enter the key and press Enter\n\nAA model data is cached locally for 4 hours so reopening opencode repeatedly won't hit rate limits. Use `/refresh-models` to force a fresh fetch.\n\n## Project setup\n\nThe `auto-agents` plugin creates a project `AGENTS.md` automatically on session start if one doesn't exist. It detects your stack and commands from config files.\n\nTo customise it, edit the generated `AGENTS.md` in your project root — once you remove the placeholder text, the plugin leaves it alone.\n\n**Detected automatically:**\n\n| File | What's extracted |\n|------|----------------|\n| `package.json` | Package manager (bun/pnpm/yarn/npm), dev/build/test/lint/typecheck scripts, framework (React, Next.js, Hono, Prisma, Vitest…) |\n| `Cargo.toml` | Rust project name, `cargo build/test/clippy` |\n| `go.mod` | Go module name, `go build/test ./...`, `golangci-lint run` |\n| `pyproject.toml` | Python stack (Django/FastAPI/Flask), pytest, ruff, mypy, poetry/uv |\n| `requirements.txt` / `setup.py` | Python project, pytest |\n| `Makefile` | `test`, `build`, `lint`, `dev` targets |\n\n## Configuration\n\n### opencode.json\n\nThe install script merges our settings into your existing `~/.config/opencode/opencode.json`. Changes made:\n\n- **`permission`** — added safe defaults: most things allowed, `rm -rf` requires confirmation, force-push and DROP TABLE/DATABASE are blocked\n- **`mcp.context7`** — added and enabled (free library docs MCP, no API key needed)\n\nYour existing settings (`model`, `provider`, other MCPs, etc.) are untouched.\n\nReference config is in `opencode.json` in this repo.\n\n### tui.json\n\nThe install script creates or updates `~/.config/opencode/tui.json` to register the model recommender TUI plugin. If the file already exists, the plugin entry is appended to the existing `plugin` array.\n\n### Enabling/disabling Context7\n\nContext7 is enabled by default. To disable:\n```json\n{ \"mcp\": { \"context7\": { \"enabled\": false } } }\n```\n\nUse it in prompts with: `use context7` — e.g. \"How do I configure Hono middleware? use context7\"\n\nOr add to your project `AGENTS.md`:\n```\nWhen looking up library or framework docs, use the context7 tool.\n```\n\n## Repository structure\n\n```\nopencode-smarts/\n├── install.sh                  # Symlink installer + opencode.json/tui.json merge\n├── opencode.json               # Config template (permissions, context7 MCP)\n├── templates/\n│   └── global-agents.md        # Global rules → ~/.config/opencode/AGENTS.md\n├── agents/\n│   ├── build.md                # Primary agent override — full git workflow\n│   ├── explorer.md             # Read-only codebase analyst\n│   ├── code-explorer.md        # Stricter read-only analyst (locked permissions)\n│   ├── planner.md              # Implementation architect\n│   ├── reviewer.md             # Code reviewer\n│   ├── code-reviewer.md        # Stricter code reviewer (parallel, confidence-scored)\n│   ├── tester.md               # Test runner and failure explainer\n│   ├── feature-dev.md          # Autonomous 7-phase feature developer\n│   └── ralph-loop.md           # Iterative loop agent\n├── commands/\n│   ├── feature.md              # /feature\n│   ├── fix.md                  # /fix\n│   ├── review.md               # /review\n│   ├── pr.md                   # /pr\n│   └── explore.md              # /explore\n├── skills/\n│   ├── feature-build/SKILL.md\n│   ├── bug-fix/SKILL.md\n│   ├── smart-commit/SKILL.md\n│   ├── smart-pr/SKILL.md\n│   └── code-review/SKILL.md\n└── plugins/\n    ├── auto-agents.ts          # Session-start AGENTS.md auto-detection\n    ├── auto-license.ts         # Session-start GPLv3 license auto-creation\n    ├── model-recommender.tsx   # TUI sidebar: best free + paid model recommendations\n    ├── openrouter-models-fix.ts # Adds all free OpenRouter models to the model picker\n    ├── rule-reinforcement.ts   # Re-injects critical rules on every LLM call + compaction\n    └── auto-version-bump.ts   # Bumps version file after each semantic commit\n```\n\n## Uninstall\n\n```bash\nrm ~/.config/opencode/AGENTS.md\nrm -rf ~/.config/opencode/agents/\nrm -rf ~/.config/opencode/skills/\nrm -rf ~/.config/opencode/commands/\nrm -rf ~/.config/opencode/plugins/\n```\n\nThen manually remove the `permission` and `mcp.context7` blocks from `~/.config/opencode/opencode.json`, and remove the model-recommender entry from `~/.config/opencode/tui.json`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjukefr%2Fopencode-smarts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjukefr%2Fopencode-smarts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjukefr%2Fopencode-smarts/lists"}