Extension Path: For Developers¶
📌 What this path helps you do¶
An AI coding assistant reads files, edits code, and runs commands. It is fast and can be wrong. This path teaches you to narrow the task, understand each change, and let a person decide whether to keep it.
Recommended route: A1 → A2 → Stage 5 core 5.1–5.4 → A3. Progress through A1, A2, Stage 5, and A3; Stage 8 is recommended but does not block starting this path. Track B readers can start with Stage 7.
🎯 Learning goals¶
After this page, you can: 1. Separate what a tool is from the surface where you use it. 2. Limit files, commands, and network access before the tool acts. 3. Manage a small change with a diff, test, human review, and rollback. 4. Check code quality, agent behavior, and production telemetry separately.
🧩 Eight core terms¶
- IDE／Surface (Integrated Development Environment / interface): an IDE is a code workbench; a Surface is where you operate a tool, such as CLI, IDE, desktop, or cloud. One tool can have many Surfaces; looking like an IDE does not mean it only works in an IDE.
- Coding Agent／Harness: a Coding Agent reads code, uses tools, edits files, and continues from results. A Harness connects model, tools, rules, and execution loops. They may be in one product but are not the same thing.
- Provider／Router: a Provider supplies model services; a Router sends requests to one or more Providers. A Router is not a model and does not manage repo permissions.
- Model／Runtime: a Model generates the next content; a Runtime runs it locally or in a service. A local Runtime is not a coding agent.
- Sandbox: a limited area for running code. It reduces the blast radius but is not a perfect guarantee.
- Approval: a person explicitly permits a high-risk action. A passing Test does not grant push, merge, or deploy permission.
- Diff／Rollback: a Diff shows what changed; Rollback reverses the unwanted change. Read the Diff first so you know which files Rollback should touch.
- Eval／Observability: Eval tests quality with fixed cases; Observability records traces, logs, cost, and errors during execution.
Do not mix up OpenCode, Pi, OpenRouter, and Ollama¶
| Name | Core identity | Plain-language description |
|---|---|---|
| OpenCode | Coding Agent／Harness | Reads, edits, and tests in a code project |
| Pi | Coding Agent／Harness | Adds extensions, skills, or RPC to a small core |
| OpenRouter | API Router | Sends model requests to Providers; does not edit your repo |
| Ollama | Local Model Runtime | Runs models and an API locally; is not itself a Coding Agent |
OpenCode／Pi do the work, OpenRouter routes requests, and Ollama runs local models.
🛠 First exercise: make one small, reversible change¶
Use a disposable demo repo or a new branch. Paste this to a Coding Agent:
First make a read-only plan; do not modify any files.
Task: find one sentence in README.md that could be clearer without changing its technical meaning.
Report which sentence, why it is small scope, which test or documentation check to run, and how to rollback.
Before my explicit human Approval, do not write files. After approval, modify only README.md.
Show git diff -- README.md and report the Test result. Do not push, merge, or deploy.
git diff -- README.md
# Then run this repository's documentation test or smallest relevant test
If wrong, confirm README.md has no other work and Rollback only this exercise’s change; never clear the whole worktree.
📚 Choose an entry point¶
| What you want | Start with | Why |
|---|---|---|
| Learn permission and sandbox workflows | Claude Code | Its docs separate permissions, isolation, and Surfaces |
| Work through app, CLI, IDE, or cloud | OpenAI Codex | One Coding Agent works across multiple entry points |
| Give a GitHub issue to a cloud agent | GitHub Copilot cloud agent | Understand cloud-agent versus IDE-agent mode |
| Use an open, Provider-flexible tool | OpenCode | Keep Agent, Provider, and Router distinct |
| Start in an IDE with step-by-step Approval | Cline | Practice approving tools, files, and browser actions |
Do not ask only “which is strongest?” Ask what files and commands it can access, whether it can connect to the network, who approves high-risk actions, and how failure is reversed.
📖 Required reading¶
Read in order, answering one question for each:
1. Claude Code permissions: what do allow, ask, and deny mean?
2. OpenAI Codex agent approvals & security: how do Sandbox, Approval, and network controls work together?
3. GitHub Copilot cloud agent: where do cloud and IDE agent modes run?
4. Pi — Permissions & Containerization: who is responsible without a built-in permission Sandbox?
5. OpenRouter provider selection: how does a Router select a Provider?
6. Ollama docs: what does a Local Model Runtime provide, and what does it not provide?
⭐ Curated tools and projects¶
Tool identity, Surface, license, and repository status were checked against official documentation and the GitHub API on 2026-08-29 UTC. Ratings are editorial ratings for this map, not GitHub stars or performance rankings.
| Category | Official tool / project | Core identity | Main Surface | Good for | Status, license, and limits | Rating |
|---|---|---|---|---|---|---|
| Official / commercial Coding Agents | Claude Code | coding agent | CLI／IDE／desktop／cloud | Permissions, sandbox, project rules, and workflow | Commercial; keep permission prompts and start with a small repo | ⭐⭐⭐⭐⭐ |
| openai/codex | coding agent | app／CLI／IDE／cloud | Compare local and remote operation | Active; repository code is Apache-2.0, while app/cloud follow their service terms; do not disable required Approval or expand workspace permissions | ⭐⭐⭐⭐⭐ | |
| GitHub Copilot | coding agent／code assistant | GitHub／IDE／CLI／app | Move from IDE collaboration to issues, branches, and PRs | Commercial; Cloud Agent and IDE mode have different permissions; output needs human review | ⭐⭐⭐⭐⭐ | |
| Cursor | coding agent + AI editor | IDE／CLI／cloud／SDK | Compare editor, background agent, and other Surfaces | Commercial; check permissions and data boundaries per Surface | ⭐⭐⭐⭐⭐ | |
| Open-source Coding Agents／Harnesses | anomalyco/opencode | coding agent／harness | terminal／desktop | Switch Provider or compatible endpoint | Active; MIT; AGENTS.md has priority, with CLAUDE.md used only when absent | ⭐⭐⭐⭐⭐ |
| earendil-works/pi | coding agent／harness | terminal／SDK／RPC | Add extensions, skills, and custom workflows to a small core | Active; MIT; no built-in Sandbox, so isolate it yourself | ⭐⭐⭐⭐ | |
| Aider-AI/aider | coding agent／pair programmer | CLI | Manage small changes with Git diff, commit, and undo | Active; Apache-2.0; auto-commit does not skip hooks | ⭐⭐⭐⭐⭐ | |
| aaif-goose/goose | coding／general agent | CLI／desktop／API | Connect Providers, MCP, and extensions | Active; Apache-2.0; start with low-privilege extensions | ⭐⭐⭐⭐ | |
| cline/cline | coding agent | IDE／CLI／SDK | Approve tools, files, and browser actions step by step | Active; Apache-2.0; an IDE Surface is not a safety guarantee | ⭐⭐⭐⭐⭐ | |
| OpenHands/OpenHands | software-development agent platform | web／CLI／SDK／cloud | Handle a fuller issue in an isolated environment | Active; MIT; larger tasks need checkpoints and human review | ⭐⭐⭐⭐ | |
| Workflow support | obra/superpowers | workflow collection | agent plugin／skills | Planning, TDD, debugging, and review workflows | Active; MIT; adapt templates to your repo gate | ⭐⭐⭐⭐ |
| yamadashy/repomix | repo context packer | CLI／MCP | Prepare one-time codebase context | Active; MIT; exclude secrets and unnecessary files before output | ⭐⭐⭐⭐⭐ | |
| Maintenance / history | continuedev/continue | coding agent | CLI／VS Code／JetBrains | Study the history of open-source editor-agent integration | Read-only; Apache-2.0; official 2.0.0 is the last version and it is no longer actively maintained | ⭐⭐⭐⭐ |
| Roo Code | coding agent | VS Code extension | Study multi-mode agent design history | Archived; Apache-2.0; use a maintained tool for new projects | ⭐⭐⭐ |
✅ Completion check and next stop¶
- I can explain Coding Agent／Harness, Router, and Local Model Runtime.
- The tool gives a read-only plan and changes one file only after human Approval.
- I read the complete Diff and ran the relevant Test.
- I know how to Rollback only this change, and the tool did not push, merge, or deploy.
Next stop: design Skills／MCP with Stage 5; build Eval, Observability, and production gates with Stage 7; compare CLI agents in the CLI agent guide.
⏱ Expand: time, environment, cost, and secret boundaries
The first exercise takes about 20–40 minutes. Use a disposable repo or new branch, check git status, and do not let an agent overwrite work from a colleague or another tool. Keep API keys in environment variables or a secret store, not prompts, README files, or commits. Disable unnecessary network, external-directory, and shell access. Cost varies with Model, Provider, input, and retries. Sandbox limits the blast radius; protect external services, credentials, and human Approval separately.
🧪 Expand: from daily changes to team workflows
Daily development¶
plan → human Approval → small change → diff → test → review → commit. Every step should be stoppable.
PR review¶
Treat agent advice as candidate findings; require files, behavior, reproduction, and a suggested Test. Unsupported guesses must not block.
CI¶
Use read-only tokens, minimum repository permissions, and fixed inputs. Do not turn Issue, PR, or web text directly into executable commands. Keep releases, merges, and secrets behind extra Approval.
Batch refactoring¶
Build baseline tests, then work by module. Each batch gets a checkpoint, Diff, and Rollback; do not hand over the whole repo at once.
🧯 Expand: common mistakes, alternatives, and rollback
| Problem | Use this instead |
|---|---|
| An IDE screen makes you think the tool only works in an IDE | Separate core identity from every Surface |
| Treating OpenRouter, Ollama, and OpenCode as one category | Choose Router, Runtime, and Coding Agent separately |
| Accepting a green Test immediately | Read the Diff, confirm coverage, then approve |
| Judging safety by line count | Check scope, testability, reversibility, and readable Diff |
| Skipping hooks because Aider auto-commits | Enable required verification/hooks and follow the review gate |
| Multiple tools edit one file simultaneously | Clarify ownership, use separate worktrees, and integrate manually |
Rollback only confirmed targets after checking git status and Diff; never use a broad reset to erase others’ work. |