inside-coding-agents

KO | EN

gitlite — search

#awesome-list #android #awesome #generative-ai #docker #python #security #nodejs #claude #command-line

inside-coding-agents

(★ 9)

Visual, evidence-backed handbook and lab for coding agent architecture, agent harness design, tools, context, sandboxing, and reproducible traces.

파일 탐색기

ZIP 다운로드

- - claim-correction.yml
  - config.yml
  - experiment-reproduction.yml
- - ci.yml
  - pages.yml
- dependabot.yml
- PULL_REQUEST_TEMPLATE.md
- - .gitignore
  - eslint.config.mjs
  - lighthouserc.cjs
  - next-env.d.ts
  - next.config.ts
  - package-lock.json
  - package.json
  - playwright.config.mjs
  - postcss.config.mjs
  - README.md
  - security-audit-allowlist.json
  - tsconfig.json
  - vite.config.ts
- - README.md
- - README.md
- - __init__.py
  - checkpoint.py
  - context.py
  - memory.py
  - model.py
  - runtime.py
  - safety.py
  - sandbox.py
  - session.py
  - tools.py
  - trace.py
  - trust.py
  - types.py
- - __init__.py
  - common.py
- - __init__.py
  - test_course_contract.py
  - test_lesson_content.py
  - test_mechanism_content.py
  - test_narrative_provenance.py
  - test_vertical_slice.py
- __init__.py
- catalog.json
- golden.py
- README.md
- - README.md
- - README.md
- - README.md
- - README.md
  - reference-approval-binding-v1.scenario.json
  - reference-checkpoint-rollback-v1.scenario.json
  - reference-context-budget-v1.scenario.json
  - reference-context-compaction-v1.scenario.json
  - reference-memory-retrieval-v1.scenario.json
  - reference-project-trust-v1.scenario.json
  - reference-sandbox-network-v1.scenario.json
  - reference-session-replay-v1.scenario.json
  - reference-stream-normalization-v1.scenario.json
  - reference-tool-roundtrip-v1.scenario.json
- - __init__.py
  - test_reproduce.py
  - test_runner.py
- __init__.py
- README.md
- reproduce.py
- runner.py
- - README.md
- - claude-code.agent.json
  - codex.agent.json
  - grok-build.agent.json
  - opencode.agent.json
  - pi.agent.json
  - README.md
  - reasonix.agent.json
  - reference-harness.agent.json
- - claude-code-doc-agent-teams.claim.json
  - claude-code-doc-execution-policy.claim.json
  - claude-code-doc-hooks.claim.json
  - claude-code-doc-subagents.claim.json
  - codex-cli-terminal-loop.claim.json
  - codex-source-agent-loop.claim.json
  - codex-source-app-server.claim.json
  - codex-source-auto-compaction.claim.json
  - codex-source-event-stream.claim.json
  - codex-source-execution-policy.claim.json
  - codex-source-extension-runtime.claim.json
  - codex-source-subagent-routing.claim.json
  - codex-source-tool-router.claim.json
  - grok-build-source-acp-interface.claim.json
  - grok-build-source-agent-loop.claim.json
  - grok-build-source-context-compaction.claim.json
  - grok-build-source-event-log.claim.json
  - grok-build-source-execution-policy.claim.json
  - grok-build-source-extension-runtime.claim.json
  - grok-build-source-retry-policy.claim.json
  - grok-build-source-subagent-runtime.claim.json
  - grok-build-source-tool-bridge.claim.json
  - opencode-source-agent-loop.claim.json
  - opencode-source-client-server.claim.json
  - opencode-source-context-compaction.claim.json
  - opencode-source-event-bridge.claim.json
  - opencode-source-execution-policy.claim.json
  - opencode-source-extension-runtime.claim.json
  - opencode-source-retry-policy.claim.json
  - opencode-source-subagent-sessions.claim.json
  - opencode-source-tool-registry.claim.json
  - pi-source-agent-loop.claim.json
  - pi-source-context-compaction.claim.json
  - pi-source-execution-boundary.claim.json
  - pi-source-extension-runtime.claim.json
  - pi-source-orchestration-boundary.claim.json
  - pi-source-rpc-mode.claim.json
  - pi-source-session-events.claim.json
  - pi-source-tool-dispatch.claim.json
  - README.md
  - reasonix-source-acp.claim.json
  - reasonix-source-agent-loop.claim.json
  - reasonix-source-context-maintenance.claim.json
  - reasonix-source-event-log.claim.json
  - reasonix-source-execution-policy.claim.json
  - reasonix-source-extension-runtime.claim.json
  - reasonix-source-retry-recovery.claim.json
  - reasonix-source-subagents.claim.json
  - reasonix-source-tool-dispatch.claim.json
  - reference-harness-controlled-tool-roundtrip.claim.json
- - example-agent.agent.json
  - example-claim.claim.json
  - example-experiment.experiment.json
  - example-mechanism.mechanism.json
  - example-trace.jsonl
- - README.md
  - reference-approval-binding-v1.experiment.json
  - reference-checkpoint-rollback-v1.experiment.json
  - reference-context-budget-v1.experiment.json
  - reference-context-compaction-v1.experiment.json
  - reference-memory-retrieval-v1.experiment.json
  - reference-project-trust-v1.experiment.json
  - reference-sandbox-network-v1.experiment.json
  - reference-session-replay-v1.experiment.json
  - reference-stream-normalization-v1.experiment.json
  - reference-tool-roundtrip-v1.experiment.json
- - agent-loop.mechanism.json
  - checkpoint-rollback.mechanism.json
  - client-server-protocol.mechanism.json
  - context-budget.mechanism.json
  - context-compaction.mechanism.json
  - event-stream.mechanism.json
  - execution-policy.mechanism.json
  - extension-runtime.mechanism.json
  - instruction-discovery.mechanism.json
  - memory-retrieval.mechanism.json
  - network-boundary.mechanism.json
  - os-sandbox.mechanism.json
  - path-boundary.mechanism.json
  - project-trust.mechanism.json
  - README.md
  - retry-recovery.mechanism.json
  - session-replay.mechanism.json
  - subagent-orchestration.mechanism.json
  - tool-dispatch.mechanism.json
  - tool-output-truncation.mechanism.json
  - workspace-tools.mechanism.json
- - agent-profile.schema.json
  - claim.schema.json
  - curriculum-catalog.schema.json
  - experiment-result.schema.json
  - experiment.schema.json
  - lab-scenario.schema.json
  - mechanism.schema.json
  - README.md
  - trace-event.schema.json
- README.md
- - __init__.py
  - test_freshness.py
  - test_public_safety.py
- check_freshness.py
- check_public_safety.py
- validate_registry.py
.gitignore
CONTRIBUTING.md
LICENSE
README.md
README.zh-CN.md
REPRODUCING.md
REPRODUCING.zh-CN.md
requirements-dev.txt
SECURITY.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> A visual, evidence-backed handbook and reproducible lab for coding agent architecture and agent harness engineering.

**English** | [简体中文](README.zh-CN.md)

[Open the live website](https://vpromise.github.io/inside-coding-agents/)

[![CI](https://github.com/vpromise/inside-coding-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/vpromise/inside-coding-agents/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://raw.githubusercontent.com/vpromise/inside-coding-agents/main/LICENSE)
[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](https://raw.githubusercontent.com/vpromise/inside-coding-agents/main/curriculum/README.md)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://raw.githubusercontent.com/vpromise/inside-coding-agents/main/apps/web/README.md)

![Inside Coding Agents: learn agent harness architecture beyond the model](https://raw.githubusercontent.com/vpromise/inside-coding-agents/main/apps/web/public/og.png)

Inside Coding Agents is an open-source, bilingual textbook, architecture atlas, and laboratory for understanding **coding agents** and the **agent harness** around an LLM. It turns agent loops, tool calling, context management, workspace access, instruction discovery, sandboxing, permissions, subagents, protocols, extensions, retries, and traces into runnable lessons and inspectable evidence.

Study how systems such as **Codex, Claude Code, OpenCode, Grok Build, Pi, and Reasonix** approach shared engineering problems. Then run the provider-neutral reference harness and reproduce the same concepts without an API key.

> This is an independent educational and research project. Product names belong to their respective owners; inclusion does not imply affiliation or endorsement.

## Why this project exists

A model can propose the next action. A useful coding agent still needs a system that owns state, exposes tools, applies policy, manages context, observes effects, and decides when the task is finished.

Most resources explain one product or show one toy loop. Inside Coding Agents connects three levels in one content graph:

- **Learn it:** small, deterministic Python lessons build a harness mechanism by mechanism.
- **Inspect it:** versioned Agent snapshots separate verified facts from interpretation.
- **Reproduce it:** controlled experiments publish fixtures, normalized traces, results, and failure boundaries.

The same material is useful as a beginner's coding-agent tutorial, an engineer's architecture reference, and a researcher's evidence index.

## Explore the project

| View | What it answers | Start here |
| --- | --- | --- |
| Academy | How do I build a coding agent from zero? | [Run the thirteen lessons](curriculum/README.md) |
| Mechanisms | What design problems do all agent harnesses share? | [Browse 20 mechanisms](content/mechanisms/README.md) |
| Agent Atlas | How does a specific agent implement those mechanisms? | [Inspect versioned profiles](content/agents/README.md) |
| Architecture Compare | Where do agent harness designs align or remain unknown? | [Compare evidence by mechanism](https://vpromise.github.io/inside-coding-agents/compare/) |
| Evidence Explorer | Which primary source supports a specific claim? | [Filter 78 evidence records](https://vpromise.github.io/inside-coding-agents/evidence/) |
| Experiment Lab | Which observations can be reproduced under fixed conditions? | [Replay 10 controlled experiments](labs/README.md) |
| Registry | Where are claims, evidence, schemas, and stable IDs stored? | [Read the data model](registry/README.md) |
| Web | How does the shared graph become a bilingual, searchable site? | [Run the interface](apps/web/README.md) |

### Included in the current public preview

- 13 runnable bilingual long-form tutorials, progressing through agent loops, context, approval, sandbox and network policy, project trust, and scoped Git rollback;
- 20 cross-agent mechanism records, with bilingual L0–L4 deep dives for context budget, compaction, memory, permissions, OS sandboxing, and checkpoint/rollback;
- 7 Agent profiles, 11 immutable snapshots, and 49 reviewed claims;
- a typed narrative-provenance gate: vendor architecture statements resolve to reviewed Claim/Evidence or an explicit gap, while Reference Harness behavior resolves to runnable traces and controlled experiments;
- pinned public-source maps for Codex, OpenCode, Grok Build, Pi, and Reasonix;
- a clean-room, official-document snapshot for Claude Code, including subagents and experimental Agent Teams;
- 10 controlled experiments, 20 reproduced traces, structured results, and readable reports;
- a zero-model-call independent reproduction reporter, bilingual runbook, integrity-checked JSON report, and public submission form;
- a bilingual, searchable website with Architecture Compare, 78-record Evidence Explorer, Agent timelines, structural Snapshot Diff, interactive Architecture Atlas, and generic data-driven routes;
- an automatic 90-day snapshot freshness gate that runs in CI every week without rewriting research claims;
- automated axe WCAG A/AA scans across 14 representative route families, reviewed desktop/mobile screenshot regression, and Lighthouse category budgets;
- JSON Schema, graph, digest, trace, link, safety, and web-build validation.

## Quick start

The lessons and controlled experiment are deterministic and require no model account or API key. Python 3.12+ and Node.js 22.13+ match CI.

```bash
git clone https://github.com/vpromise/inside-coding-agents.git
cd inside-coding-agents

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt

# Build the smallest agent loop and print its Trace 0.1 events.
python -m curriculum.lessons.s01_agent_loop.demo

# Check the committed experiment without modifying files.
python labs/runner.py reference-tool-roundtrip-v1 --check

# Generate a public-safe independent reproduction report from this clean commit.
python labs/reproduce.py reference-tool-roundtrip-v1 \
  --output reproduction-report.json

# Validate schemas, evidence links, graph references, digests, and traces.
python scripts/validate_registry.py
```

Run the interactive site:

```bash
cd apps/web
npm ci
npm run dev
```

Run the complete local quality gate:

```bash
python -m unittest discover -s scripts/tests -v
python -m unittest discover -s curriculum/tests -v
python -m unittest discover -s labs/tests -v
python labs/runner.py reference-tool-roundtrip-v1 --check
python scripts/validate_registry.py

cd apps/web
npm run audit:ci
npm run lint
npm run typecheck
npm test
npx playwright install chromium
npm run test:browser
npm run test:lighthouse
npm run test:pages
```

## Agent coverage

The Atlas is a versioned evidence index, not a popularity ranking or benchmark leaderboard.

| Agent | Evidence surface | Snapshots | Reviewed claims |
| --- | --- | ---: | ---: |
| Claude Code | Official documentation; clean-room boundary | 1 | 4 |
| Codex | Pinned public source and official documentation | 3 | 9 |
| Grok Build | Pinned public source and official documentation | 1 | 9 |
| OpenCode | Pinned public source and official documentation | 1 | 9 |
| Pi | Pinned public source | 2 | 8 |
| Reasonix | Pinned public source | 2 | 9 |
| Reference Harness | Repository source and controlled reproduction | 1 | 1 |

Every architecture claim is attached to an Agent snapshot and one or more evidence records:

- `source` — a public source location pinned to a commit;
- `official-doc` — first-party product or project documentation;
- `reproduced` — an observation from a fixed, inspectable experiment;
- `inference` — an explicitly labeled interpretation with stated uncertainty.

Closed-source behavior is never presented as an internal implementation fact. Model quality, product defaults, and harness design are kept separate wherever the evidence allows it.

## How the knowledge graph works

```text
Mechanism
  ├── Lessons and runnable reference code
  ├── Agent implementations and versioned snapshots
  ├── Atomic claims and public evidence
  ├── Experiments, results, and normalized traces
  └── Bilingual pages and search entries
```

Stable IDs connect the graph. The Registry is the fact layer; Markdown is the narrative layer; the website is a generated view. Adding a conforming Agent, Claim, Mechanism, or Experiment should not require a product-specific page component.

## Repository map

```text
apps/web/                 Bilingual searchable web interface
content/agents/           Agent overviews and snapshot analyses
content/mechanisms/       Long-form mechanism explanations
curriculum/               Runnable lessons and reference harness
labs/                     Fixtures, scenarios, runner, traces, results
packages/trace-schema/    Shared Trace 0.1 contract
registry/                 Schemas, profiles, claims, mechanisms, experiments
scripts/                  Validation and publication-safety gates
```

Internal planning, private research checkouts, deployment bindings, credentials, and unredacted traces are intentionally not part of this public repository.

## Frequently asked questions

### What is an agent harness?

An agent harness is the system around a model that manages the control loop, messages, tools, state, context, execution policy, workspace effects, observability, and completion. The model is an important component, but it is not the whole agent.

### Is this a framework for running production agents?

Not currently. The reference harness is deliberately small and deterministic so mechanisms stay readable. It is teaching and experiment infrastructure, not a claim of production readiness.

### Is this a benchmark comparing Codex and Claude Code?

No. The current lab validates ten mechanisms with a controlled reference harness. Cross-product results are published only when subjects, versions, permissions, environments, and observability boundaries are genuinely comparable.

### Can I add another coding agent?

Yes. Start with a versioned profile, attach atomic claims to public evidence, state closed-source and inference boundaries, and add a reproducible experiment only when one is justified. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Contributing and security

Corrections with stronger evidence, independent reproductions, new mechanisms, runnable lessons, accessibility improvements, and technically reviewed translations are welcome. Read the [contribution guide](CONTRIBUTING.md) or follow the [independent reproduction runbook](REPRODUCING.md) before opening a pull request or reproduction report.

Do not publish credentials, private source, personal data, unredacted native traces, or exploitable security details. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).

## License and attribution

The repository is licensed under [Apache License 2.0](LICENSE). Upstream source excerpts are not vendored; external claims link to their original public evidence.

The progressive, build-it-yourself teaching style was inspired in part by [shareAI-lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code). Inside Coding Agents broadens that idea into a product-neutral atlas, content graph, and reproducible lab.

inside-coding-agents

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README