anvil-engineering-workbench 1.0.4 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,787 +1,793 @@
1
- <!-- ANVIL — AI Harness for software engineering -->
2
-
3
- <p align="center">
4
- <img src="https://raw.githubusercontent.com/anvil-workbench/ANVIL/main/docs/anvil-dashboard.png?v=2" alt="ANVIL AI Harness dashboard" width="100%" />
5
- </p>
6
-
7
- <h1 align="center">ANVIL — The AI Engineering Harness</h1>
8
-
9
- <p align="center">
10
- <strong>An open-source AI engineering harness for orchestrating agents, understanding codebases, reviewing changes, and verifying results.</strong>
11
- </p>
12
-
13
- <p align="center">
14
- <a href="https://github.com/AdityaaaTiwari" style="display:inline-flex;align-items:center;gap:6px;text-decoration:none;vertical-align:middle"><img src="https://img.shields.io/badge/Author-Aditya%20Tiwari-c47b52?style=flat" alt="Aditya Tiwari" style="display:block;border:0" /></a>
15
- <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license" /></a>
16
- </p>
17
-
18
- <p align="center">
19
- <a href="https://github.com/anvil-workbench/ANVIL"><img src="https://img.shields.io/github/stars/anvil-workbench/ANVIL?style=flat" alt="GitHub stars" /></a>
20
- <a href="https://github.com/anvil-workbench/ANVIL/forks"><img src="https://img.shields.io/github/forks/anvil-workbench/ANVIL?style=flat" alt="GitHub forks" /></a>
21
- <a href="https://github.com/anvil-workbench/ANVIL/commits/main"><img src="https://img.shields.io/github/last-commit/anvil-workbench/ANVIL?style=flat" alt="Last commit" /></a>
22
- <a href="https://github.com/anvil-workbench/ANVIL/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/anvil-workbench/ANVIL/ci.yml?branch=main&style=flat&label=build" alt="Build status" /></a>
23
- </p>
24
-
25
- <p align="center">
26
- <img src="https://img.shields.io/badge/AI%20Harness-Agent%20Orchestration-7c3aed?logo=probot&logoColor=white" alt="AI harness and agent orchestration" />
27
- <img src="https://img.shields.io/badge/Agent%20Workflows-Review%20%26%20Verify-2563eb?logo=githubactions&logoColor=white" alt="Agent workflows, review and verification" />
28
- <img src="https://img.shields.io/badge/MCP-Read--only%20Tools-0f766e?logo=protocols&logoColor=white" alt="MCP read-only tools" />
29
- <img src="https://img.shields.io/badge/Runtime-Node.js%2022%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22+" />
30
- <img src="https://img.shields.io/badge/Language-TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
31
- <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-64748b?logo=linux&logoColor=white" alt="Windows macOS Linux" />
32
- <img src="https://img.shields.io/badge/Architecture-Local--first-0f766e?logo=shield&logoColor=white" alt="Local-first architecture" />
33
- </p>
34
-
35
- <p align="center">
36
- <a href="https://www.star-history.com/anvil-workbench/ANVIL">
37
- <img src="https://img.shields.io/badge/GitHub%20Trending-Not%20ranked%20yet-64748b?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Trending — not ranked yet" />
38
- </a>
39
- <a href="https://www.star-history.com/anvil-workbench/ANVIL">
40
- <img src="https://img.shields.io/badge/Star%20History%20Global%20Rank-Pending-64748b?style=for-the-badge&logo=starship&logoColor=white" alt="Star History global rank — pending" />
41
- </a>
42
- </p>
43
-
44
- <p align="center">
45
- <sub>These are live-status placeholders until Star History publishes a trending record and global rank for ANVIL. They will be replaced with Star History's live badge images once those records are available.</sub>
46
- </p>
47
-
48
- <p align="center">
49
- <strong>Built and maintained by <a href="https://github.com/AdityaaaTiwari">Aditya Tiwari</a></strong>
50
- </p>
51
-
52
- <p align="center">
53
- <a href="#quick-start">Quick start</a> ·
54
- <a href="#features">Features</a> ·
55
- <a href="#dashboard">Dashboard</a> ·
56
- <a href="#ai-providers">AI providers</a> ·
57
- <a href="#integrations">Integrations</a> ·
58
- <a href="#security-model">Security</a> ·
59
- <a href="#roadmap">Roadmap</a>
60
- </p>
61
-
62
- ---
63
-
64
- > [!NOTE]
65
- > **ANVIL v1.0.0 — AI harness foundation.** The local CLI, local dashboard, agent orchestration, MCP server, provider adapters, GitHub Action and GitHub App installation/authentication foundation are available. The GitHub App does not yet perform hosted repository scans or create pull requests. See [Current capabilities and boundaries](#current-capabilities-and-boundaries).
66
-
67
- ## What is ANVIL?
68
-
69
- **ANVIL (ANVIL Engineering Workbench)** is a local-first AI engineering harness for developers who want more than a chat window pointed at a repository.
70
-
71
- It brings codebase understanding, specialist-agent workflows, engineering review, human approval, verification, experiment tracking and a live local dashboard into one inspectable system.
72
-
73
- ANVIL is built around a simple engineering loop:
74
-
75
- ```text
76
- inspect → understand → plan → propose → review → approve → verify → learn
77
- ```
78
-
79
- The goal is not to let an agent silently take over a project. The goal is to make AI-assisted engineering **observable, reviewable and evidence-driven**: proposals remain proposals until a person approves the next step.
80
-
81
- ### At a glance
82
-
83
- | | ANVIL provides |
84
- |---|---|
85
- | **Codebase intelligence** | Project inventory, code search, architecture maps, dependency analysis and change impact |
86
- | **Agent harness** | Specialist roles, skills, hooks, provider routing, task orchestration and run history |
87
- | **Engineering control** | Review plans, patch validation, approval records, staged workflows and explicit verification |
88
- | **Evaluation loop** | Evaluation suites, benchmark matrices, regression comparisons and experiment history |
89
- | **Operator experience** | CLI, local dashboard, execution traces, configuration studio and workspace explorer |
90
- | **Interoperability** | Read-only MCP server, Claude Code CLI adapter, Cursor MCP configuration and GitHub Action |
91
-
92
- ## Quick start
93
-
94
- ### Requirements
95
-
96
- - **Node.js 22 or newer**
97
- - npm (included with Node.js)
98
- - Git (recommended for Git-aware features)
99
- - Windows, macOS or Linux
100
-
101
- Check your environment:
102
-
103
- ```bash
104
- node --version
105
- npm --version
106
- git --version
107
- ```
108
-
109
- ### Install ANVIL
110
-
111
- Install the released CLI directly from the GitHub repository:
112
-
113
- ```bash
114
- npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.0.3
115
- ```
116
-
117
- Verify the installation:
118
-
119
- ```bash
120
- anvil --version
121
- anvil --help
122
- ```
123
-
124
- ### Initialize and inspect a project
125
-
126
- Open a terminal in the repository you want to work on:
127
-
128
- ```bash
129
- cd /path/to/your-project
130
-
131
- # Initialize or auto-scaffold workspace configuration
132
- anvil doctor --fix
133
-
134
- # Clean temporary farzi files, caches, and auto-fix code issues
135
- anvil clean . --apply --fix
136
-
137
- # Inspect the project
138
- anvil inspect .
139
-
140
- # Start the local dashboard
141
- anvil dashboard .
142
- ```
143
-
144
- ANVIL prints the dashboard's local URL. Open that address in your browser.
145
-
146
- ### Windows PowerShell
147
-
148
- ```powershell
149
- # Check prerequisites
150
- node --version
151
- npm --version
152
- git --version
153
-
154
- # Install ANVIL
155
- npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.0.4
156
-
157
- # Move into your project
158
- cd C:\Users\YourName\Projects\my-project
159
-
160
- # Initialize, clean, inspect and launch
161
- anvil doctor --fix
162
- anvil clean . --apply --fix
163
- anvil inspect .
164
- anvil dashboard .
165
- ```
166
-
167
- Replace the example directory with your actual project path.
168
-
169
- ### Build from source
170
-
171
- For contributors or anyone who wants to work on ANVIL itself:
172
-
173
- ```bash
174
- git clone https://github.com/anvil-workbench/ANVIL.git
175
- cd ANVIL
176
- npm ci
177
- npm run typecheck
178
- npm test
179
- npm run build
180
- ```
181
-
182
- ## Features
183
-
184
- ANVIL is composed of focused engineering systems that share local project context and persisted evidence.
185
-
186
- ### 1. Project and code intelligence
187
-
188
- Understand a repository before asking an agent to change it.
189
-
190
- - **Project inspection** — detect languages, frameworks, package managers, dependencies, scripts and project structure.
191
- - **Code search** — search supported source files and inspect bounded matching context.
192
- - **Architecture mapping** — map source modules, entry points and internal import relationships.
193
- - **Dependency intelligence** — inspect npm dependency information, licenses and imported security reports.
194
- - **Dependency impact** — identify downstream modules affected by a change.
195
- - **Git intelligence** — analyze working-tree changes, changed files and suggested test targets.
196
- - **Change intelligence** — combine changed-file context, dependency impact and engineering signals.
197
- - **Engineering risk** — rank potential hotspots using dependency and quality evidence.
198
- - **Project health** — produce a unified health snapshot with evidence coverage and quality signals.
199
- - **Timeline snapshots** — capture and compare local engineering-intelligence snapshots.
200
-
201
- ### 2. Specialist agents and orchestration
202
-
203
- Coordinate engineering tasks with explicit task state instead of relying on one long prompt.
204
-
205
- - Built-in specialist-agent registry and workspace-defined agent roles.
206
- - Workspace skill registry and skill selection.
207
- - Project context assembly and local project memory.
208
- - Declarative before-agent hooks and permission policies.
209
- - Provider routing for configured AI backends.
210
- - Dependency-aware review-plan generation.
211
- - Saved runs, task-level status and approval checkpoints.
212
- - Run replay for retryable failed tasks.
213
- - Resume support for pending or approved work.
214
- - Execution traces and per-agent telemetry.
215
- - Configurable token and task-duration budgets.
216
-
217
- Agent instructions and workspace files are treated as untrusted project content. A generated plan or response does not mean a project file has been changed.
218
-
219
- ### 3. Code review and patch lifecycle
220
-
221
- Keep analysis, approval and file promotion as distinct operations.
222
-
223
- - Static code review and evidence-backed findings.
224
- - Optional provider-backed AI review suggestions.
225
- - Saved review snapshots, review history and comparison.
226
- - Patch validation as a dry run.
227
- - Approval records tied to patch and source fingerprints.
228
- - Staged patch review and staged verification workflows.
229
- - Explicit operator-controlled promotion boundaries.
230
-
231
- **A patch being suggested or validated is not the same as it being approved or applied.**
232
-
233
- ### 4. Verification and regression intelligence
234
-
235
- Run checks deliberately and retain their outcomes.
236
-
237
- - Discover available project checks without executing them.
238
- - Run one explicitly selected verification script.
239
- - Persist verification results and history.
240
- - Compare verification history with current Git changes.
241
- - Generate regression intelligence from verification and impact signals.
242
- - Verify approved staged patches in a temporary workspace.
243
- - Inspect Docker availability, security profiles and sandbox compliance.
244
- - Review managed-container cleanup activity.
245
-
246
- Local script verification runs project-controlled code on the host. Docker-backed verification is opt-in and depends on the host's Docker configuration.
247
-
248
- ### 5. Evaluation, benchmarking and improvement
249
-
250
- Measure candidate configurations instead of silently changing agent behavior.
251
-
252
- - Local evaluation suites and run scoring.
253
- - Benchmark trials and benchmark matrices.
254
- - Baseline-versus-candidate regression comparisons.
255
- - Model and skill experiment scaffolding.
256
- - Experiment manifests and experiment history.
257
- - Agent effectiveness intelligence.
258
- - Agent optimization recommendations.
259
- - Controlled agent-evolution assessments.
260
- - Agent/skill configuration snapshots and diffs.
261
- - Benchmark-gated configuration release preparation and human approval.
262
-
263
- Configuration promotion is reviewable. ANVIL does not silently rewrite its own agent or skill setup based on an evaluation result.
264
-
265
- ### 6. Security and policy
266
-
267
- Security-related features focus on inspectable boundaries and bounded operations.
268
-
269
- - Static agent-configuration audits for supported agent, skill, hook and permission files.
270
- - Redaction of credential-like matches in audit output.
271
- - Fail-closed permission-policy validation.
272
- - Workspace path restrictions and symlink rejection in bounded readers.
273
- - Patch/source fingerprint checks for approval records.
274
- - Sandbox policy validation and compliance reporting.
275
- - Explicit review of stopped ANVIL-managed containers before cleanup.
276
-
277
- These controls reduce risk; they do not certify a repository or make arbitrary host execution safe.
278
-
279
- ## Dashboard
280
-
281
- The **anvil dashboard** is a browser-based engineering control center served by the local CLI.
282
-
283
- Start it from the project you want to inspect:
284
-
285
- ```bash
286
- anvil dashboard .
287
- ```
288
-
289
- The terminal prints a localhost URL. The dashboard reads the selected workspace and its local ANVIL records.
290
-
291
- ### Dashboard workspaces
292
-
293
- | Area | What you can inspect or manage |
294
- |---|---|
295
- | **Overview** | Project summary, detected stack and workspace status |
296
- | **Health** | Quality signals, health snapshots and engineering trends |
297
- | **Architecture** | Project structure, module relationships and dependency views |
298
- | **Agents** | Built-in and workspace specialist-agent registry |
299
- | **Runs & tasks** | Saved orchestration runs, task states and execution details |
300
- | **Approvals** | Human review and approval records |
301
- | **Workflow editor** | Draft and save reusable specialist-agent workflows |
302
- | **Configuration studio** | Workspace agent/skill Markdown, snapshots and configuration comparisons |
303
- | **Workspace explorer** | Browse supported project files and inspect source |
304
- | **Code search** | Search source and view bounded matching context |
305
- | **Reviews** | Review findings, saved review snapshots and comparisons |
306
- | **Verification** | Selected check results and verification history |
307
- | **Traces** | Execution telemetry and per-agent activity |
308
- | **Regression** | Compare verification outcomes and engineering signals |
309
- | **Evaluations** | Evaluation suites, benchmark results and experiment comparisons |
310
- | **Provider readiness** | Inspect provider configuration and run explicit connection diagnostics |
311
-
312
- Some dashboard panels depend on local history, a configured provider or enabled workspace permissions.
313
-
314
- ### Public website vs local dashboard
315
-
316
- These are two different experiences:
317
-
318
- - **[ANVIL.vercel.app](https://ANVIL.vercel.app/)** is the public product website.
319
- - **`anvil dashboard .`** starts the actual interactive dashboard on your machine and connects it to the selected local project.
320
-
321
- The public website does not host your local project dashboard.
322
-
323
- ## CLI reference
324
-
325
- Run `anvil --help` for the complete command list and `anvil <command> --help` for command-specific usage.
326
-
327
- ### Everyday project commands
328
-
329
- | Command | Purpose |
330
- |---|---|
331
- | `anvil init [path]` | Create a local `.ANVIL` starter workspace |
332
- | `anvil clean [path]` | Scan & scrub farzi files, logs, temp downloads; add `--apply` to delete, `--fix` to repair code, `--verify` to run test gate |
333
- | `anvil fix [path]` | Auto-repair code: prune unused imports, normalize whitespace and blank lines; add `--verify` |
334
- | `anvil undo [path]` | Instant single-command rollback of last clean/fix operation using saved snapshot backup |
335
- | `anvil hook install` | Install automated ANVIL quality gate into `.git/hooks/pre-commit` |
336
- | `anvil inspect [path]` | Inspect project languages, tooling, dependencies and scripts |
337
- | `anvil map [path]` | Map source modules and import relationships |
338
- | `anvil dashboard [path]` | Start the local dashboard |
339
- | `anvil quality [path]` | Generate a static engineering-quality report |
340
- | `anvil deps [path]` | Analyze npm dependencies, licenses and imported security reports |
341
- | `anvil health [path]` | Generate a unified project-health snapshot |
342
- | `anvil deep [path]` | Analyze AST symbols, circular imports and change impact |
343
- | `anvil git [path]` | Analyze changed files, impact and suggested tests |
344
- | `anvil risk [path]` | Rank engineering hotspots |
345
- | `anvil change-risk [path]` | Analyze changed-file risk and downstream impact |
346
- | `anvil snapshot [path]` | Capture an intelligence snapshot |
347
- | `anvil timeline [path]` | Compare the latest intelligence snapshots |
348
-
349
- ### Agents and runs
350
-
351
- | Command | Purpose |
352
- |---|---|
353
- | `anvil agents [path]` | List specialist-agent roles |
354
- | `anvil skills [path]` | List built-in and workspace skills |
355
- | `anvil hooks [path]` | List declarative lifecycle hooks |
356
- | `anvil memory <action>` | Add, list, remove or inspect project memory |
357
- | `anvil plan --goal TEXT` | Create and save a reviewable draft plan |
358
- | `anvil run --goal TEXT` | Run a plan with the configured AI provider |
359
- | `anvil runs [path]` | List saved local runs |
360
- | `anvil show-run ID` | Display a saved run |
361
- | `anvil approve RUN_ID TASK_ID` | Approve a task awaiting human review |
362
- | `anvil resume RUN_ID` | Continue pending or approved tasks |
363
- | `anvil replay RUN_ID` | Create a run from retryable failed tasks |
364
- | `anvil trace RUN_ID` | Show per-agent execution telemetry |
365
-
366
- ### Review and verification
367
-
368
- | Command | Purpose |
369
- |---|---|
370
- | `anvil review [path]` | Review changed source files |
371
- | `anvil review [path] --ai` | Include provider-backed review suggestions |
372
- | `anvil review-history [path]` | List saved review snapshots |
373
- | `anvil review-show ID` | Display a saved review |
374
- | `anvil review-compare A B` | Compare two saved reviews |
375
- | `anvil patch-check ID N` | Dry-run validate a proposed patch |
376
- | `anvil verify --list` | Discover available npm scripts without running them |
377
- | `anvil verify SCRIPT` | Explicitly run one selected npm script |
378
- | `anvil verify-history` | List saved verification runs |
379
- | `anvil regression [path]` | Compare verification history with Git changes and impact |
380
- | `anvil patch-verify ID SCRIPT` | Verify an approved staged patch in a temporary workspace |
381
-
382
- ### Evaluation and agent configuration
383
-
384
- | Command | Purpose |
385
- |---|---|
386
- | `anvil evals [path]` | List local evaluation suites |
387
- | `anvil evaluate RUN_ID` | Score a saved run against an evaluation suite |
388
- | `anvil benchmark` | Record or view benchmark results |
389
- | `anvil benchmark-matrix` | Run a configured model comparison matrix |
390
- | `anvil benchmark-regression` | Compare a matrix with its baseline |
391
- | `anvil optimize-agents` | Recommend evidence-based agent improvements |
392
- | `anvil agent-intelligence` | Score agent effectiveness across benchmark history |
393
- | `anvil agent-evolution` | Assess a controlled baseline/treatment experiment |
394
- | `anvil experiment-studio` | Create or compare skill/model experiments |
395
- | `anvil experiment-history` | Rank historical benchmark candidates |
396
- | `anvil agent-config` | Snapshot, list, show and diff agent configuration |
397
- | `anvil agent-release` | Prepare and review benchmark-gated configuration releases |
398
- | `anvil experiment` | Capture, show and compare reproducible experiment manifests |
399
-
400
- ### Sandbox and diagnostics
401
-
402
- | Command | Purpose |
403
- |---|---|
404
- | `anvil doctor [path]` | Environment health checks; add `--fix` to auto-scaffold missing config, .gitignore & .env |
405
- | `anvil sandbox-status` | Inspect Docker availability and advertised security options |
406
- | `anvil sandbox-compliance` | Generate a sandbox compliance report |
407
- | `anvil sandbox-policy-check` | Validate a fail-closed sandbox policy |
408
- | `anvil sandbox-profiles` | List or inspect built-in security profiles |
409
- | `anvil sandbox-cleanup` | Review stopped ANVIL containers; `--apply` opts into removal |
410
- | `anvil sandbox-cleanup-history` | Show recorded cleanup activity |
411
- | `anvil agent-security [path]` | Audit supported agent instructions, skills, hooks and permissions |
412
-
413
- Most project commands accept a project path. Use `--json` where supported for machine-readable output.
414
-
415
- ## AI providers
416
-
417
- ANVIL supports provider adapters for local CLI and HTTP-based model services. Configure one provider using environment variables.
418
-
419
- | Provider | Environment | Default model |
420
- |---|---|---|
421
- | Claude Code CLI | Authenticated Claude Code CLI on PATH | `sonnet` |
422
- | OpenAI | `ANVIL_API_KEY` or `OPENAI_API_KEY` | `gpt-4.1-mini` |
423
- | Anthropic API | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5` |
424
- | Google AI | `GOOGLE_API_KEY` | `gemini-2.5-flash` |
425
- | Ollama | Local Ollama endpoint | `llama3.2` |
426
-
427
- Set `ANVIL_AI_PROVIDER` to the provider name and optionally set `ANVIL_AI_MODEL` to override the model. `ANVIL_BASE_URL` selects a compatible gateway/custom endpoint. For Ollama, `OLLAMA_HOST` overrides the default local endpoint.
428
-
429
- ### Examples
430
-
431
- ```bash
432
- # OpenAI
433
- ANVIL_AI_PROVIDER=openai OPENAI_API_KEY=YOUR_KEY ANVIL run --goal "Review the authentication flow" --path .
434
-
435
- # Anthropic
436
- ANVIL_AI_PROVIDER=anthropic ANTHROPIC_API_KEY=YOUR_KEY ANVIL run --goal "Map the service boundaries" --path .
437
-
438
- # Google Gemini
439
- ANVIL_AI_PROVIDER=google GOOGLE_API_KEY=YOUR_KEY ANVIL run --goal "Identify reliability risks" --path .
440
-
441
- # Local Ollama
442
- ANVIL_AI_PROVIDER=ollama OLLAMA_HOST=http://localhost:11434 ANVIL_AI_MODEL=llama3.2 ANVIL run --goal "Explain the architecture" --path .
443
-
444
- # Claude Code CLI
445
- ANVIL_AI_PROVIDER=claude-code ANVIL_AI_MODEL=sonnet ANVIL run --goal "Plan a safe refactor" --path .
446
- ```
447
-
448
- > [!IMPORTANT]
449
- > Provider calls may send task prompts, dependency results and selected project context to the configured service. Hosted API use may incur charges. A consumer chat subscription does not automatically include API credits. Review [provider configuration and data-handling notes](docs/providers.md) before using private repositories.
450
-
451
- ### Provider connection diagnostics
452
-
453
- The local dashboard includes explicit connection checks for OpenAI, Anthropic, Google and Ollama. These checks make a read-only model-list request; they do not submit a generation prompt. A successful connection check does not guarantee generation access to every model.
454
-
455
- ## Integrations
456
-
457
- ### Claude Code
458
-
459
- ANVIL includes a local Claude Code CLI provider adapter. It uses the CLI installed and authenticated on the developer's machine; it is not the same as configuring an Anthropic API key.
460
-
461
- See [Claude Code integration](docs/integrations/claude-code.md).
462
-
463
- ### Cursor and MCP
464
-
465
- Cursor can connect to ANVIL through the local stdio MCP server using Cursor's MCP configuration. This is **MCP interoperability**, not a native Cursor extension.
466
-
467
- Example project configuration:
468
-
469
- ```json
470
- {
471
- "mcpServers": {
472
- "ANVIL": {
473
- "command": "node",
474
- "args": ["C:/path/to/ANVIL/dist/mcp/server.js"],
475
- "env": {
476
- "ANVIL_WORKSPACE": "C:/path/to/your-project"
477
- }
478
- }
479
- }
480
- }
481
- ```
482
-
483
- Build ANVIL before using the compiled server:
484
-
485
- ```bash
486
- npm run build
487
- ```
488
-
489
- Adjust the paths for your machine. See [Cursor MCP documentation](https://docs.cursor.com/context/mcp).
490
-
491
- ### MCP server
492
-
493
- ANVIL provides a Model Context Protocol server over stdio:
494
-
495
- ```bash
496
- npm run build
497
- ANVIL_WORKSPACE=/absolute/path/to/project npm run mcp
498
- ```
499
-
500
- The current MCP server exposes nine bounded, read-only tools:
501
-
502
- | Tool | Function |
503
- |---|---|
504
- | `ANVIL_inspect_project` | Inspect project structure and tooling |
505
- | `ANVIL_map_architecture` | Map source files and imports |
506
- | `ANVIL_search_code` | Search supported project source |
507
- | `ANVIL_list_files` | List supported workspace files |
508
- | `ANVIL_read_file` | Read a bounded text/source file |
509
- | `ANVIL_quality_audit` | Run static project-quality checks |
510
- | `ANVIL_git_intelligence` | Analyze Git changes and impact |
511
- | `ANVIL_list_agents` | List built-in and workspace agent roles |
512
- | `ANVIL_create_review_plan` | Create a draft engineering review plan |
513
-
514
- MCP workspace paths are constrained to the configured workspace root. Hidden paths, generated/dependency directories, secret-like filenames and symlinks are excluded or rejected. Reads are bounded. The MCP server does not expose arbitrary shell execution, project-file writes, patch application or test execution.
515
-
516
- Some workspace browsing/search operations require an explicit restricted-mode allowlist in `.ANVIL/permissions.json`; the default proposal-only policy denies them.
517
-
518
- ### GitHub Action
519
-
520
- ANVIL ships a composite GitHub Action for selected CI operations.
521
-
522
- ```yaml
523
- name: ANVIL checks
524
-
525
- on:
526
- pull_request:
527
- push:
528
- branches: [main]
529
-
530
- jobs:
531
- ANVIL:
532
- runs-on: ubuntu-latest
533
- steps:
534
- - uses: actions/checkout@v4
535
- - uses: anvil-workbench/ANVIL@v1.0.3
536
- with:
537
- version: v1.0.3
538
- project-path: .
539
- operation: inspect
540
- ```
541
-
542
- Supported `operation` values:
543
-
544
- | Operation | What it runs |
545
- |---|---|
546
- | `inspect` | Project inspection |
547
- | `quality` | Static engineering-quality audit |
548
- | `health` | Project-health report |
549
- | `review` | Code review |
550
-
551
- Inputs are `version`, `project-path` and `operation`. The default operation is `inspect`. Pin production workflows to a reviewed release tag or immutable commit SHA. See [action.yml](action.yml).
552
-
553
- ### GitHub App
554
-
555
- [**Get the ANVIL GitHub App →**](https://ANVIL.vercel.app/api/github/install)
556
-
557
- The GitHub App currently provides an installation entry point, signed installation webhooks, OAuth account authorization, verified installation association and server-side session handling.
558
-
559
- **Not shipped yet:** hosted repository-content scanning, installation-token-based repository workflows, automatic pull-request creation and hosted autonomous coding agents. Installing the App does not upload or scan a local workspace. Use the local CLI/dashboard for repository analysis today.
560
-
561
- See [GitHub App integration notes](docs/integrations/github-app.md) for endpoints, settings and security details.
562
-
563
- ## Architecture
564
-
565
- ANVIL is a TypeScript/Node.js application with a CLI entry point and focused core modules.
566
-
567
- ```text
568
- Developer / CI
569
- |
570
- +----------------+----------------+
571
- | | |
572
- ANVIL CLI GitHub Action MCP clients
573
- src/cli.ts action.yml stdio transport
574
- | | |
575
- +----------------+----------------+
576
- |
577
- ANVIL Core Engine
578
- |
579
- +----------------+------+-------+----------------+
580
- | | | |
581
- Intelligence Agents & Review & Evaluation &
582
- & Analysis Orchestration Verification Experimentation
583
- | | | |
584
- +----------------+------+-------+----------------+
585
- |
586
- Local workspace state
587
- .ANVIL/
588
- |
589
- Local Dashboard UI
590
- src/core/dashboard-server.ts
591
- ```
592
-
593
- ### Repository layout
594
-
595
- ```text
596
- ANVIL/
597
- ├── .ANVIL/ # Built-in evaluation data
598
- ├── .github/workflows/ # CI, release and sandbox workflows
599
- ├── api/
600
- │ ├── _lib/ # GitHub App, OAuth and storage helpers
601
- │ └── github/ # Install, auth, setup and webhook endpoints
602
- ├── docs/
603
- │ ├── integrations/ # Claude Code and GitHub App guides
604
- │ ├── providers.md # Provider setup and diagnostics
605
- │ └── ANVIL-CAPABILITY-ROADMAP.md
606
- ├── public/
607
- │ ├── index.html # Public product website
608
- │ └── *.svg # ANVIL brand artwork
609
- ├── src/
610
- │ ├── ai/ # Provider adapters
611
- │ ├── core/ # Engineering workbench modules
612
- │ ├── mcp/ # MCP server and workspace path policy
613
- │ └── cli.ts # CLI entry point
614
- ├── tests/ # Unit and integration tests
615
- ├── action.yml # Reusable GitHub composite Action
616
- ├── CHANGELOG.md
617
- ├── CONTRIBUTING.md
618
- ├── LICENSE
619
- ├── package.json
620
- ├── README.md
621
- └── SECURITY.md
622
- ```
623
-
624
- ### Core module map
625
-
626
- | Module group | Responsibilities |
627
- |---|---|
628
- | Project intelligence | Inspection, code search, architecture maps, dependency graphs and impact |
629
- | Quality and risk | Quality audits, health snapshots, engineering risk and change intelligence |
630
- | Agent system | Agent registry, workspace context, skills, hooks, model routing and orchestration |
631
- | Run lifecycle | Run persistence, task settlement, approvals, replay, resume and traces |
632
- | Review lifecycle | Static/AI review, review history, patch validation, approval and staging |
633
- | Verification | Script discovery, explicit verification, staged verification and history |
634
- | Sandbox | Container runtime, security profiles, policy, compliance and cleanup audit |
635
- | Evaluation | Evaluation suites, benchmarks, matrices, regression and experiment history |
636
- | Agent improvement | Optimization plans, config snapshots, evolution and release gates |
637
- | Workspace interface | Local dashboard, workspace browser and bounded MCP tools |
638
-
639
- ## Security model
640
-
641
- ANVIL is designed to keep consequential operations explicit and inspectable.
642
-
643
- - **Local-first by default:** the dashboard runs on loopback and reads the workspace selected by the CLI.
644
- - **Bounded workspace access:** path resolution rejects traversal and symlinks; readers exclude hidden, generated, dependency and secret-like paths.
645
- - **Read-only MCP tools:** the MCP server does not expose arbitrary shell execution or workspace writes.
646
- - **Fail-closed policies:** malformed or unsupported permission policies are not treated as permission grants.
647
- - **Review before promotion:** patch validation is a dry run; approval records bind to patch and source fingerprints; staging is separate from promotion.
648
- - **Explicit verification:** the operator chooses which named check to run.
649
- - **Redacted audit output:** credential-like matches are redacted by the static agent-configuration audit.
650
- - **Opt-in Docker workflows:** Docker-backed verification and cleanup operations are separate and require explicit operator action.
651
-
652
- > [!WARNING]
653
- > ANVIL is an early-stage engineering tool. Local script verification executes project-controlled code on the host; it is **not** an OS sandbox. Docker security depends on the host runtime and selected configuration. Static audits and heuristic risk scores are not security certifications. AI review may send selected source excerpts to the provider you configure.
654
-
655
- Read [SECURITY.md](SECURITY.md) before using ANVIL with untrusted repositories, agent instructions or project scripts.
656
-
657
- ## Current capabilities and boundaries
658
-
659
- The v1.0 release establishes the local engineering workbench foundation.
660
-
661
- | Area | v1.0 status |
662
- |---|---|
663
- | CLI and local workspace | Available |
664
- | Interactive local dashboard | Available |
665
- | Project/code/dependency intelligence | Available |
666
- | Agent registry, skills, hooks and orchestration | Available |
667
- | Review, patch validation and approval records | Available |
668
- | Verification, regression and history | Available |
669
- | Evaluation, benchmark and experiment workflows | Available |
670
- | MCP server with bounded read-only tools | Available |
671
- | Claude Code CLI provider adapter | Available |
672
- | OpenAI, Anthropic, Google and Ollama adapters | Available |
673
- | GitHub composite Action | Available |
674
- | GitHub App installation and OAuth foundation | Available |
675
- | Hosted repository scanning through the GitHub App | Not implemented |
676
- | Hosted automatic pull-request creation | Not implemented |
677
- | Hosted autonomous coding agents | Not implemented |
678
- | Native Cursor/VS Code IDE extension | Not shipped |
679
- | Hosted multi-user dashboard | Not shipped |
680
-
681
- This table is intentional: a roadmap item is not a shipped feature. The project tracks planned work in the [ANVIL Capability Roadmap](docs/ANVIL-CAPABILITY-ROADMAP.md).
682
-
683
- ## Roadmap
684
-
685
- ANVIL's direction is to grow into a complete, local-first agent engineering harness while preserving clear permission boundaries.
686
-
687
- - **Agent and skill ecosystem:** expand specialist roles, skill packs, compatibility metadata and lifecycle management.
688
- - **Memory and context:** structured memory layers with provenance, retrieval and retention controls.
689
- - **Hooks and policy:** more lifecycle events, deterministic policy evaluation and auditable presets.
690
- - **Planning and execution:** reusable workflows, checkpoints, cancellation and durable recovery.
691
- - **Quality and verification:** independent review passes, verification profiles and evidence-linked reports.
692
- - **Security:** broader configuration scanning, supply-chain checks and posture reports.
693
- - **Integrations:** stable adapter interfaces and a truthful harness compatibility matrix.
694
- - **Learning loop:** evidence-based lessons and regression-gated, human-approved configuration releases.
695
- - **Operator experience:** unified setup/doctor/status commands, export/import and migration tools.
696
-
697
- See [docs/ANVIL-CAPABILITY-ROADMAP.md](docs/ANVIL-CAPABILITY-ROADMAP.md) for the detailed delivery sequence and non-negotiable product rules.
698
-
699
- ## Development
700
-
701
- ### Clone and install
702
-
703
- ```bash
704
- git clone https://github.com/anvil-workbench/ANVIL.git
705
- cd ANVIL
706
- npm ci
707
- ```
708
-
709
- ### Quality checks
710
-
711
- ```bash
712
- npm run typecheck
713
- npm test
714
- npm run build
715
- ```
716
-
717
- ### npm scripts
718
-
719
- | Script | Purpose |
720
- |---|---|
721
- | `npm run dev` | Run the TypeScript CLI during development |
722
- | `npm run build` | Compile TypeScript into `dist/` |
723
- | `npm run typecheck` | Type-check without emitting files |
724
- | `npm test` | Run the Vitest test suite |
725
- | `npm run test:watch` | Run Vitest in watch mode |
726
- | `npm run mcp` | Start the built MCP server |
727
-
728
- ### Contributing
729
-
730
- 1. Open an issue to discuss substantial changes.
731
- 2. Keep pull requests focused and explain the user problem.
732
- 3. Add or update tests for behavior changes.
733
- 4. Document permission and security implications.
734
- 5. Never commit credentials, tokens, private keys or local workspace data.
735
- 6. Run type checking, tests and the production build before submitting.
736
-
737
- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
738
-
739
- ## Project history
740
-
741
- ANVIL's v1.0.3 release brings full multi-language architecture mapping, automated farzi-file scrubbing, code auto-repair, one-command doctor self-healing, the local CLI, dashboard, engineering intelligence, agent workflows, MCP integration, GitHub Action and GitHub App installation foundation into one versioned product.
742
-
743
- The project is maintained as an original ANVIL codebase. ECC is a capability and documentation reference; ANVIL maintains its own identity, implementation, data models and roadmap.
744
-
745
- For release-by-release changes, see [CHANGELOG.md](CHANGELOG.md).
746
-
747
- ## Project links
748
-
749
- | Resource | Link |
750
- |---|---|
751
- | Product website | [ANVIL.vercel.app](https://ANVIL.vercel.app/) |
752
- | Get the GitHub App | [Install ANVIL](https://ANVIL.vercel.app/api/github/install) |
753
- | Source repository | [anvil-workbench/ANVIL](https://github.com/anvil-workbench/ANVIL) |
754
- | Organization | [ANVIL WORKBENCH](https://github.com/anvil-workbench) |
755
- | Releases | [GitHub Releases](https://github.com/anvil-workbench/ANVIL/releases) |
756
- | Issues and bugs | [GitHub Issues](https://github.com/anvil-workbench/ANVIL/issues) |
757
- | CI and automation | [GitHub Actions](https://github.com/anvil-workbench/ANVIL/actions) |
758
- | Roadmap | [Capability Roadmap](docs/ANVIL-CAPABILITY-ROADMAP.md) |
759
- | Changelog | [CHANGELOG.md](CHANGELOG.md) |
760
- | Provider guide | [docs/providers.md](docs/providers.md) |
761
- | GitHub App guide | [GitHub App integration](docs/integrations/github-app.md) |
762
- | Security policy | [SECURITY.md](SECURITY.md) |
763
- | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
764
-
765
- ## Support
766
-
767
- For questions about ANVIL or help with the GitHub App, contact [m.g.atiwari28@gmail.com](mailto:m.g.atiwari28@gmail.com).
768
-
769
- ## Maintainer
770
-
771
- **Aditya Tiwari** · [@AdityaaaTiwari](https://github.com/AdityaaaTiwari)
772
-
773
- ## License
774
-
775
- ANVIL is open source under the [MIT License](LICENSE).
776
-
777
- ## Star history
778
-
779
- <p align="center">
780
- <a href="https://www.star-history.com/anvil-workbench/ANVIL">
781
- <picture>
782
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=anvil-workbench/ANVIL&type=Date&theme=dark" />
783
- <img src="https://api.star-history.com/svg?repos=anvil-workbench/ANVIL&type=Date" alt="ANVIL GitHub star history" width="100%" />
784
- </picture>
785
- </a>
786
- </p>
787
-
1
+ <!-- ANVIL — AI Harness for software engineering -->
2
+
3
+ <p align="center">
4
+ <img src="https://raw.githubusercontent.com/anvil-workbench/ANVIL/main/docs/anvil-dashboard.png?v=2" alt="ANVIL AI Harness dashboard" width="100%" />
5
+ </p>
6
+
7
+ <h1 align="center">ANVIL — The AI Engineering Harness</h1>
8
+
9
+ <p align="center">
10
+ <strong>An open-source AI engineering harness for orchestrating agents, understanding codebases, reviewing changes, and verifying results.</strong>
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://github.com/AdityaaaTiwari" style="display:inline-flex;align-items:center;gap:6px;text-decoration:none;vertical-align:middle"><img src="https://img.shields.io/badge/Author-Aditya%20Tiwari-c47b52?style=flat" alt="Aditya Tiwari" style="display:block;border:0" /></a>
15
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license" /></a>
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="https://github.com/anvil-workbench/ANVIL"><img src="https://img.shields.io/github/stars/anvil-workbench/ANVIL?style=flat" alt="GitHub stars" /></a>
20
+ <a href="https://github.com/anvil-workbench/ANVIL/forks"><img src="https://img.shields.io/github/forks/anvil-workbench/ANVIL?style=flat" alt="GitHub forks" /></a>
21
+ <a href="https://github.com/anvil-workbench/ANVIL/commits/main"><img src="https://img.shields.io/github/last-commit/anvil-workbench/ANVIL?style=flat" alt="Last commit" /></a>
22
+ <a href="https://github.com/anvil-workbench/ANVIL/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/anvil-workbench/ANVIL/ci.yml?branch=main&style=flat&label=build" alt="Build status" /></a>
23
+ </p>
24
+
25
+ <p align="center">
26
+ <img src="https://img.shields.io/badge/AI%20Harness-Agent%20Orchestration-7c3aed?logo=probot&logoColor=white" alt="AI harness and agent orchestration" />
27
+ <img src="https://img.shields.io/badge/Agent%20Workflows-Review%20%26%20Verify-2563eb?logo=githubactions&logoColor=white" alt="Agent workflows, review and verification" />
28
+ <img src="https://img.shields.io/badge/MCP-Read--only%20Tools-0f766e?logo=protocols&logoColor=white" alt="MCP read-only tools" />
29
+ <img src="https://img.shields.io/badge/Runtime-Node.js%2022%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22+" />
30
+ <img src="https://img.shields.io/badge/Language-TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
31
+ <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-64748b?logo=linux&logoColor=white" alt="Windows macOS Linux" />
32
+ <img src="https://img.shields.io/badge/Architecture-Local--first-0f766e?logo=shield&logoColor=white" alt="Local-first architecture" />
33
+ </p>
34
+
35
+ <p align="center">
36
+ <a href="https://www.star-history.com/anvil-workbench/ANVIL">
37
+ <img src="https://img.shields.io/badge/GitHub%20Trending-Not%20ranked%20yet-64748b?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Trending — not ranked yet" />
38
+ </a>
39
+ <a href="https://www.star-history.com/anvil-workbench/ANVIL">
40
+ <img src="https://img.shields.io/badge/Star%20History%20Global%20Rank-Pending-64748b?style=for-the-badge&logo=starship&logoColor=white" alt="Star History global rank — pending" />
41
+ </a>
42
+ </p>
43
+
44
+ <p align="center">
45
+ <sub>These are live-status placeholders until Star History publishes a trending record and global rank for ANVIL. They will be replaced with Star History's live badge images once those records are available.</sub>
46
+ </p>
47
+
48
+ <p align="center">
49
+ <strong>Built and maintained by <a href="https://github.com/AdityaaaTiwari">Aditya Tiwari</a></strong>
50
+ </p>
51
+
52
+ <p align="center">
53
+ <a href="#quick-start">Quick start</a> ·
54
+ <a href="#features">Features</a> ·
55
+ <a href="#dashboard">Dashboard</a> ·
56
+ <a href="#ai-providers">AI providers</a> ·
57
+ <a href="#integrations">Integrations</a> ·
58
+ <a href="#security-model">Security</a> ·
59
+ <a href="#roadmap">Roadmap</a>
60
+ </p>
61
+
62
+ ---
63
+
64
+ > [!NOTE]
65
+ > **ANVIL v1.0.5 — AI harness foundation.** The local CLI, local dashboard, agent orchestration, MCP server, provider adapters, GitHub Action, automated self-healing cleaner, byte-accurate rollback (`anvil undo`), pre-commit hooks (`anvil hook install`), and GitHub App installation/authentication foundation are available. See [Current capabilities and boundaries](#current-capabilities-and-boundaries).
66
+
67
+ ## What is ANVIL?
68
+
69
+ **ANVIL (ANVIL Engineering Workbench)** is a local-first AI engineering harness for developers who want more than a chat window pointed at a repository.
70
+
71
+ It brings codebase understanding, specialist-agent workflows, engineering review, human approval, verification, experiment tracking and a live local dashboard into one inspectable system.
72
+
73
+ ANVIL is built around a simple engineering loop:
74
+
75
+ ```text
76
+ inspect → understand → plan → propose → review → approve → verify → learn
77
+ ```
78
+
79
+ The goal is not to let an agent silently take over a project. The goal is to make AI-assisted engineering **observable, reviewable and evidence-driven**: proposals remain proposals until a person approves the next step.
80
+
81
+ ### At a glance
82
+
83
+ | | ANVIL provides |
84
+ |---|---|
85
+ | **Codebase intelligence** | Project inventory, code search, architecture maps, dependency analysis and change impact |
86
+ | **Agent harness** | Specialist roles, skills, hooks, provider routing, task orchestration and run history |
87
+ | **Engineering control** | Review plans, patch validation, approval records, staged workflows and explicit verification |
88
+ | **Evaluation loop** | Evaluation suites, benchmark matrices, regression comparisons and experiment history |
89
+ | **Operator experience** | CLI, local dashboard, execution traces, configuration studio and workspace explorer |
90
+ | **Interoperability** | Read-only MCP server, Claude Code CLI adapter, Cursor MCP configuration and GitHub Action |
91
+
92
+ ## Quick start
93
+
94
+ ### Requirements
95
+
96
+ - **Node.js 22 or newer**
97
+ - npm (included with Node.js)
98
+ - Git (recommended for Git-aware features)
99
+ - Windows, macOS or Linux
100
+
101
+ Check your environment:
102
+
103
+ ```bash
104
+ node --version
105
+ npm --version
106
+ git --version
107
+ ```
108
+
109
+ ### Install ANVIL
110
+
111
+ Install the released CLI via npm:
112
+
113
+ ```bash
114
+ npm install --global anvil-engineering-workbench
115
+ ```
116
+
117
+ Or install directly from the GitHub repository:
118
+
119
+ ```bash
120
+ npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.0.5
121
+ ```
122
+
123
+ Verify the installation:
124
+
125
+ ```bash
126
+ anvil --version
127
+ anvil --help
128
+ ```
129
+
130
+ ### Initialize and inspect a project
131
+
132
+ Open a terminal in the repository you want to work on:
133
+
134
+ ```bash
135
+ cd /path/to/your-project
136
+
137
+ # Initialize or auto-scaffold workspace configuration
138
+ anvil doctor --fix
139
+
140
+ # Clean temporary farzi files, caches, and auto-fix code issues
141
+ anvil clean . --apply --fix
142
+
143
+ # Inspect the project
144
+ anvil inspect .
145
+
146
+ # Start the local dashboard
147
+ anvil dashboard .
148
+ ```
149
+
150
+ ANVIL prints the dashboard's local URL. Open that address in your browser.
151
+
152
+ ### Windows PowerShell
153
+
154
+ ```powershell
155
+ # Check prerequisites
156
+ node --version
157
+ npm --version
158
+ git --version
159
+
160
+ # Install ANVIL
161
+ npm install --global git+https://github.com/anvil-workbench/ANVIL.git#v1.0.5
162
+
163
+ # Move into your project
164
+ cd C:\Users\YourName\Projects\my-project
165
+
166
+ # Initialize, clean, inspect and launch
167
+ anvil doctor --fix
168
+ anvil clean . --apply --fix
169
+ anvil inspect .
170
+ anvil dashboard .
171
+ ```
172
+
173
+ Replace the example directory with your actual project path.
174
+
175
+ ### Build from source
176
+
177
+ For contributors or anyone who wants to work on ANVIL itself:
178
+
179
+ ```bash
180
+ git clone https://github.com/anvil-workbench/ANVIL.git
181
+ cd ANVIL
182
+ npm ci
183
+ npm run typecheck
184
+ npm test
185
+ npm run build
186
+ ```
187
+
188
+ ## Features
189
+
190
+ ANVIL is composed of focused engineering systems that share local project context and persisted evidence.
191
+
192
+ ### 1. Project and code intelligence
193
+
194
+ Understand a repository before asking an agent to change it.
195
+
196
+ - **Project inspection** — detect languages, frameworks, package managers, dependencies, scripts and project structure.
197
+ - **Code search** — search supported source files and inspect bounded matching context.
198
+ - **Architecture mapping** — map source modules, entry points and internal import relationships.
199
+ - **Dependency intelligence** — inspect npm dependency information, licenses and imported security reports.
200
+ - **Dependency impact** — identify downstream modules affected by a change.
201
+ - **Git intelligence** — analyze working-tree changes, changed files and suggested test targets.
202
+ - **Change intelligence** — combine changed-file context, dependency impact and engineering signals.
203
+ - **Engineering risk** — rank potential hotspots using dependency and quality evidence.
204
+ - **Project health** — produce a unified health snapshot with evidence coverage and quality signals.
205
+ - **Timeline snapshots** — capture and compare local engineering-intelligence snapshots.
206
+
207
+ ### 2. Specialist agents and orchestration
208
+
209
+ Coordinate engineering tasks with explicit task state instead of relying on one long prompt.
210
+
211
+ - Built-in specialist-agent registry and workspace-defined agent roles.
212
+ - Workspace skill registry and skill selection.
213
+ - Project context assembly and local project memory.
214
+ - Declarative before-agent hooks and permission policies.
215
+ - Provider routing for configured AI backends.
216
+ - Dependency-aware review-plan generation.
217
+ - Saved runs, task-level status and approval checkpoints.
218
+ - Run replay for retryable failed tasks.
219
+ - Resume support for pending or approved work.
220
+ - Execution traces and per-agent telemetry.
221
+ - Configurable token and task-duration budgets.
222
+
223
+ Agent instructions and workspace files are treated as untrusted project content. A generated plan or response does not mean a project file has been changed.
224
+
225
+ ### 3. Code review and patch lifecycle
226
+
227
+ Keep analysis, approval and file promotion as distinct operations.
228
+
229
+ - Static code review and evidence-backed findings.
230
+ - Optional provider-backed AI review suggestions.
231
+ - Saved review snapshots, review history and comparison.
232
+ - Patch validation as a dry run.
233
+ - Approval records tied to patch and source fingerprints.
234
+ - Staged patch review and staged verification workflows.
235
+ - Explicit operator-controlled promotion boundaries.
236
+
237
+ **A patch being suggested or validated is not the same as it being approved or applied.**
238
+
239
+ ### 4. Verification and regression intelligence
240
+
241
+ Run checks deliberately and retain their outcomes.
242
+
243
+ - Discover available project checks without executing them.
244
+ - Run one explicitly selected verification script.
245
+ - Persist verification results and history.
246
+ - Compare verification history with current Git changes.
247
+ - Generate regression intelligence from verification and impact signals.
248
+ - Verify approved staged patches in a temporary workspace.
249
+ - Inspect Docker availability, security profiles and sandbox compliance.
250
+ - Review managed-container cleanup activity.
251
+
252
+ Local script verification runs project-controlled code on the host. Docker-backed verification is opt-in and depends on the host's Docker configuration.
253
+
254
+ ### 5. Evaluation, benchmarking and improvement
255
+
256
+ Measure candidate configurations instead of silently changing agent behavior.
257
+
258
+ - Local evaluation suites and run scoring.
259
+ - Benchmark trials and benchmark matrices.
260
+ - Baseline-versus-candidate regression comparisons.
261
+ - Model and skill experiment scaffolding.
262
+ - Experiment manifests and experiment history.
263
+ - Agent effectiveness intelligence.
264
+ - Agent optimization recommendations.
265
+ - Controlled agent-evolution assessments.
266
+ - Agent/skill configuration snapshots and diffs.
267
+ - Benchmark-gated configuration release preparation and human approval.
268
+
269
+ Configuration promotion is reviewable. ANVIL does not silently rewrite its own agent or skill setup based on an evaluation result.
270
+
271
+ ### 6. Security and policy
272
+
273
+ Security-related features focus on inspectable boundaries and bounded operations.
274
+
275
+ - Static agent-configuration audits for supported agent, skill, hook and permission files.
276
+ - Redaction of credential-like matches in audit output.
277
+ - Fail-closed permission-policy validation.
278
+ - Workspace path restrictions and symlink rejection in bounded readers.
279
+ - Patch/source fingerprint checks for approval records.
280
+ - Sandbox policy validation and compliance reporting.
281
+ - Explicit review of stopped ANVIL-managed containers before cleanup.
282
+
283
+ These controls reduce risk; they do not certify a repository or make arbitrary host execution safe.
284
+
285
+ ## Dashboard
286
+
287
+ The **anvil dashboard** is a browser-based engineering control center served by the local CLI.
288
+
289
+ Start it from the project you want to inspect:
290
+
291
+ ```bash
292
+ anvil dashboard .
293
+ ```
294
+
295
+ The terminal prints a localhost URL. The dashboard reads the selected workspace and its local ANVIL records.
296
+
297
+ ### Dashboard workspaces
298
+
299
+ | Area | What you can inspect or manage |
300
+ |---|---|
301
+ | **Overview** | Project summary, detected stack and workspace status |
302
+ | **Health** | Quality signals, health snapshots and engineering trends |
303
+ | **Architecture** | Project structure, module relationships and dependency views |
304
+ | **Agents** | Built-in and workspace specialist-agent registry |
305
+ | **Runs & tasks** | Saved orchestration runs, task states and execution details |
306
+ | **Approvals** | Human review and approval records |
307
+ | **Workflow editor** | Draft and save reusable specialist-agent workflows |
308
+ | **Configuration studio** | Workspace agent/skill Markdown, snapshots and configuration comparisons |
309
+ | **Workspace explorer** | Browse supported project files and inspect source |
310
+ | **Code search** | Search source and view bounded matching context |
311
+ | **Reviews** | Review findings, saved review snapshots and comparisons |
312
+ | **Verification** | Selected check results and verification history |
313
+ | **Traces** | Execution telemetry and per-agent activity |
314
+ | **Regression** | Compare verification outcomes and engineering signals |
315
+ | **Evaluations** | Evaluation suites, benchmark results and experiment comparisons |
316
+ | **Provider readiness** | Inspect provider configuration and run explicit connection diagnostics |
317
+
318
+ Some dashboard panels depend on local history, a configured provider or enabled workspace permissions.
319
+
320
+ ### Public website vs local dashboard
321
+
322
+ These are two different experiences:
323
+
324
+ - **[ANVIL.vercel.app](https://ANVIL.vercel.app/)** is the public product website.
325
+ - **`anvil dashboard .`** starts the actual interactive dashboard on your machine and connects it to the selected local project.
326
+
327
+ The public website does not host your local project dashboard.
328
+
329
+ ## CLI reference
330
+
331
+ Run `anvil --help` for the complete command list and `anvil <command> --help` for command-specific usage.
332
+
333
+ ### Everyday project commands
334
+
335
+ | Command | Purpose |
336
+ |---|---|
337
+ | `anvil init [path]` | Create a local `.ANVIL` starter workspace |
338
+ | `anvil clean [path]` | Scan & scrub farzi files, logs, temp downloads; add `--apply` to delete, `--fix` to repair code, `--verify` to run test gate |
339
+ | `anvil fix [path]` | Auto-repair code: prune unused imports, normalize whitespace and blank lines; add `--verify` |
340
+ | `anvil undo [path]` | Instant single-command rollback of last clean/fix operation using saved snapshot backup |
341
+ | `anvil hook install` | Install automated ANVIL quality gate into `.git/hooks/pre-commit` |
342
+ | `anvil inspect [path]` | Inspect project languages, tooling, dependencies and scripts |
343
+ | `anvil map [path]` | Map source modules and import relationships |
344
+ | `anvil dashboard [path]` | Start the local dashboard |
345
+ | `anvil quality [path]` | Generate a static engineering-quality report |
346
+ | `anvil deps [path]` | Analyze npm dependencies, licenses and imported security reports |
347
+ | `anvil health [path]` | Generate a unified project-health snapshot |
348
+ | `anvil deep [path]` | Analyze AST symbols, circular imports and change impact |
349
+ | `anvil git [path]` | Analyze changed files, impact and suggested tests |
350
+ | `anvil risk [path]` | Rank engineering hotspots |
351
+ | `anvil change-risk [path]` | Analyze changed-file risk and downstream impact |
352
+ | `anvil snapshot [path]` | Capture an intelligence snapshot |
353
+ | `anvil timeline [path]` | Compare the latest intelligence snapshots |
354
+
355
+ ### Agents and runs
356
+
357
+ | Command | Purpose |
358
+ |---|---|
359
+ | `anvil agents [path]` | List specialist-agent roles |
360
+ | `anvil skills [path]` | List built-in and workspace skills |
361
+ | `anvil hooks [path]` | List declarative lifecycle hooks |
362
+ | `anvil memory <action>` | Add, list, remove or inspect project memory |
363
+ | `anvil plan --goal TEXT` | Create and save a reviewable draft plan |
364
+ | `anvil run --goal TEXT` | Run a plan with the configured AI provider |
365
+ | `anvil runs [path]` | List saved local runs |
366
+ | `anvil show-run ID` | Display a saved run |
367
+ | `anvil approve RUN_ID TASK_ID` | Approve a task awaiting human review |
368
+ | `anvil resume RUN_ID` | Continue pending or approved tasks |
369
+ | `anvil replay RUN_ID` | Create a run from retryable failed tasks |
370
+ | `anvil trace RUN_ID` | Show per-agent execution telemetry |
371
+
372
+ ### Review and verification
373
+
374
+ | Command | Purpose |
375
+ |---|---|
376
+ | `anvil review [path]` | Review changed source files |
377
+ | `anvil review [path] --ai` | Include provider-backed review suggestions |
378
+ | `anvil review-history [path]` | List saved review snapshots |
379
+ | `anvil review-show ID` | Display a saved review |
380
+ | `anvil review-compare A B` | Compare two saved reviews |
381
+ | `anvil patch-check ID N` | Dry-run validate a proposed patch |
382
+ | `anvil verify --list` | Discover available npm scripts without running them |
383
+ | `anvil verify SCRIPT` | Explicitly run one selected npm script |
384
+ | `anvil verify-history` | List saved verification runs |
385
+ | `anvil regression [path]` | Compare verification history with Git changes and impact |
386
+ | `anvil patch-verify ID SCRIPT` | Verify an approved staged patch in a temporary workspace |
387
+
388
+ ### Evaluation and agent configuration
389
+
390
+ | Command | Purpose |
391
+ |---|---|
392
+ | `anvil evals [path]` | List local evaluation suites |
393
+ | `anvil evaluate RUN_ID` | Score a saved run against an evaluation suite |
394
+ | `anvil benchmark` | Record or view benchmark results |
395
+ | `anvil benchmark-matrix` | Run a configured model comparison matrix |
396
+ | `anvil benchmark-regression` | Compare a matrix with its baseline |
397
+ | `anvil optimize-agents` | Recommend evidence-based agent improvements |
398
+ | `anvil agent-intelligence` | Score agent effectiveness across benchmark history |
399
+ | `anvil agent-evolution` | Assess a controlled baseline/treatment experiment |
400
+ | `anvil experiment-studio` | Create or compare skill/model experiments |
401
+ | `anvil experiment-history` | Rank historical benchmark candidates |
402
+ | `anvil agent-config` | Snapshot, list, show and diff agent configuration |
403
+ | `anvil agent-release` | Prepare and review benchmark-gated configuration releases |
404
+ | `anvil experiment` | Capture, show and compare reproducible experiment manifests |
405
+
406
+ ### Sandbox and diagnostics
407
+
408
+ | Command | Purpose |
409
+ |---|---|
410
+ | `anvil doctor [path]` | Environment health checks; add `--fix` to auto-scaffold missing config, .gitignore & .env |
411
+ | `anvil sandbox-status` | Inspect Docker availability and advertised security options |
412
+ | `anvil sandbox-compliance` | Generate a sandbox compliance report |
413
+ | `anvil sandbox-policy-check` | Validate a fail-closed sandbox policy |
414
+ | `anvil sandbox-profiles` | List or inspect built-in security profiles |
415
+ | `anvil sandbox-cleanup` | Review stopped ANVIL containers; `--apply` opts into removal |
416
+ | `anvil sandbox-cleanup-history` | Show recorded cleanup activity |
417
+ | `anvil agent-security [path]` | Audit supported agent instructions, skills, hooks and permissions |
418
+
419
+ Most project commands accept a project path. Use `--json` where supported for machine-readable output.
420
+
421
+ ## AI providers
422
+
423
+ ANVIL supports provider adapters for local CLI and HTTP-based model services. Configure one provider using environment variables.
424
+
425
+ | Provider | Environment | Default model |
426
+ |---|---|---|
427
+ | Claude Code CLI | Authenticated Claude Code CLI on PATH | `sonnet` |
428
+ | OpenAI | `ANVIL_API_KEY` or `OPENAI_API_KEY` | `gpt-4.1-mini` |
429
+ | Anthropic API | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5` |
430
+ | Google AI | `GOOGLE_API_KEY` | `gemini-2.5-flash` |
431
+ | Ollama | Local Ollama endpoint | `llama3.2` |
432
+
433
+ Set `ANVIL_AI_PROVIDER` to the provider name and optionally set `ANVIL_AI_MODEL` to override the model. `ANVIL_BASE_URL` selects a compatible gateway/custom endpoint. For Ollama, `OLLAMA_HOST` overrides the default local endpoint.
434
+
435
+ ### Examples
436
+
437
+ ```bash
438
+ # OpenAI
439
+ ANVIL_AI_PROVIDER=openai OPENAI_API_KEY=YOUR_KEY ANVIL run --goal "Review the authentication flow" --path .
440
+
441
+ # Anthropic
442
+ ANVIL_AI_PROVIDER=anthropic ANTHROPIC_API_KEY=YOUR_KEY ANVIL run --goal "Map the service boundaries" --path .
443
+
444
+ # Google Gemini
445
+ ANVIL_AI_PROVIDER=google GOOGLE_API_KEY=YOUR_KEY ANVIL run --goal "Identify reliability risks" --path .
446
+
447
+ # Local Ollama
448
+ ANVIL_AI_PROVIDER=ollama OLLAMA_HOST=http://localhost:11434 ANVIL_AI_MODEL=llama3.2 ANVIL run --goal "Explain the architecture" --path .
449
+
450
+ # Claude Code CLI
451
+ ANVIL_AI_PROVIDER=claude-code ANVIL_AI_MODEL=sonnet ANVIL run --goal "Plan a safe refactor" --path .
452
+ ```
453
+
454
+ > [!IMPORTANT]
455
+ > Provider calls may send task prompts, dependency results and selected project context to the configured service. Hosted API use may incur charges. A consumer chat subscription does not automatically include API credits. Review [provider configuration and data-handling notes](docs/providers.md) before using private repositories.
456
+
457
+ ### Provider connection diagnostics
458
+
459
+ The local dashboard includes explicit connection checks for OpenAI, Anthropic, Google and Ollama. These checks make a read-only model-list request; they do not submit a generation prompt. A successful connection check does not guarantee generation access to every model.
460
+
461
+ ## Integrations
462
+
463
+ ### Claude Code
464
+
465
+ ANVIL includes a local Claude Code CLI provider adapter. It uses the CLI installed and authenticated on the developer's machine; it is not the same as configuring an Anthropic API key.
466
+
467
+ See [Claude Code integration](docs/integrations/claude-code.md).
468
+
469
+ ### Cursor and MCP
470
+
471
+ Cursor can connect to ANVIL through the local stdio MCP server using Cursor's MCP configuration. This is **MCP interoperability**, not a native Cursor extension.
472
+
473
+ Example project configuration:
474
+
475
+ ```json
476
+ {
477
+ "mcpServers": {
478
+ "ANVIL": {
479
+ "command": "node",
480
+ "args": ["C:/path/to/ANVIL/dist/mcp/server.js"],
481
+ "env": {
482
+ "ANVIL_WORKSPACE": "C:/path/to/your-project"
483
+ }
484
+ }
485
+ }
486
+ }
487
+ ```
488
+
489
+ Build ANVIL before using the compiled server:
490
+
491
+ ```bash
492
+ npm run build
493
+ ```
494
+
495
+ Adjust the paths for your machine. See [Cursor MCP documentation](https://docs.cursor.com/context/mcp).
496
+
497
+ ### MCP server
498
+
499
+ ANVIL provides a Model Context Protocol server over stdio:
500
+
501
+ ```bash
502
+ npm run build
503
+ ANVIL_WORKSPACE=/absolute/path/to/project npm run mcp
504
+ ```
505
+
506
+ The current MCP server exposes nine bounded, read-only tools:
507
+
508
+ | Tool | Function |
509
+ |---|---|
510
+ | `ANVIL_inspect_project` | Inspect project structure and tooling |
511
+ | `ANVIL_map_architecture` | Map source files and imports |
512
+ | `ANVIL_search_code` | Search supported project source |
513
+ | `ANVIL_list_files` | List supported workspace files |
514
+ | `ANVIL_read_file` | Read a bounded text/source file |
515
+ | `ANVIL_quality_audit` | Run static project-quality checks |
516
+ | `ANVIL_git_intelligence` | Analyze Git changes and impact |
517
+ | `ANVIL_list_agents` | List built-in and workspace agent roles |
518
+ | `ANVIL_create_review_plan` | Create a draft engineering review plan |
519
+
520
+ MCP workspace paths are constrained to the configured workspace root. Hidden paths, generated/dependency directories, secret-like filenames and symlinks are excluded or rejected. Reads are bounded. The MCP server does not expose arbitrary shell execution, project-file writes, patch application or test execution.
521
+
522
+ Some workspace browsing/search operations require an explicit restricted-mode allowlist in `.ANVIL/permissions.json`; the default proposal-only policy denies them.
523
+
524
+ ### GitHub Action
525
+
526
+ ANVIL ships a composite GitHub Action for selected CI operations.
527
+
528
+ ```yaml
529
+ name: ANVIL checks
530
+
531
+ on:
532
+ pull_request:
533
+ push:
534
+ branches: [main]
535
+
536
+ jobs:
537
+ ANVIL:
538
+ runs-on: ubuntu-latest
539
+ steps:
540
+ - uses: actions/checkout@v4
541
+ - uses: anvil-workbench/ANVIL@v1.0.5
542
+ with:
543
+ version: v1.0.5
544
+ project-path: .
545
+ operation: inspect
546
+ ```
547
+
548
+ Supported `operation` values:
549
+
550
+ | Operation | What it runs |
551
+ |---|---|
552
+ | `inspect` | Project inspection |
553
+ | `quality` | Static engineering-quality audit |
554
+ | `health` | Project-health report |
555
+ | `review` | Code review |
556
+
557
+ Inputs are `version`, `project-path` and `operation`. The default operation is `inspect`. Pin production workflows to a reviewed release tag or immutable commit SHA. See [action.yml](action.yml).
558
+
559
+ ### GitHub App
560
+
561
+ [**Get the ANVIL GitHub App →**](https://ANVIL.vercel.app/api/github/install)
562
+
563
+ The GitHub App currently provides an installation entry point, signed installation webhooks, OAuth account authorization, verified installation association and server-side session handling.
564
+
565
+ **Not shipped yet:** hosted repository-content scanning, installation-token-based repository workflows, automatic pull-request creation and hosted autonomous coding agents. Installing the App does not upload or scan a local workspace. Use the local CLI/dashboard for repository analysis today.
566
+
567
+ See [GitHub App integration notes](docs/integrations/github-app.md) for endpoints, settings and security details.
568
+
569
+ ## Architecture
570
+
571
+ ANVIL is a TypeScript/Node.js application with a CLI entry point and focused core modules.
572
+
573
+ ```text
574
+ Developer / CI
575
+ |
576
+ +----------------+----------------+
577
+ | | |
578
+ ANVIL CLI GitHub Action MCP clients
579
+ src/cli.ts action.yml stdio transport
580
+ | | |
581
+ +----------------+----------------+
582
+ |
583
+ ANVIL Core Engine
584
+ |
585
+ +----------------+------+-------+----------------+
586
+ | | | |
587
+ Intelligence Agents & Review & Evaluation &
588
+ & Analysis Orchestration Verification Experimentation
589
+ | | | |
590
+ +----------------+------+-------+----------------+
591
+ |
592
+ Local workspace state
593
+ .ANVIL/
594
+ |
595
+ Local Dashboard UI
596
+ src/core/dashboard-server.ts
597
+ ```
598
+
599
+ ### Repository layout
600
+
601
+ ```text
602
+ ANVIL/
603
+ ├── .ANVIL/ # Built-in evaluation data
604
+ ├── .github/workflows/ # CI, release and sandbox workflows
605
+ ├── api/
606
+ │ ├── _lib/ # GitHub App, OAuth and storage helpers
607
+ │ └── github/ # Install, auth, setup and webhook endpoints
608
+ ├── docs/
609
+ │ ├── integrations/ # Claude Code and GitHub App guides
610
+ │ ├── providers.md # Provider setup and diagnostics
611
+ │ └── ANVIL-CAPABILITY-ROADMAP.md
612
+ ├── public/
613
+ │ ├── index.html # Public product website
614
+ │ └── *.svg # ANVIL brand artwork
615
+ ├── src/
616
+ │ ├── ai/ # Provider adapters
617
+ │ ├── core/ # Engineering workbench modules
618
+ │ ├── mcp/ # MCP server and workspace path policy
619
+ │ └── cli.ts # CLI entry point
620
+ ├── tests/ # Unit and integration tests
621
+ ├── action.yml # Reusable GitHub composite Action
622
+ ├── CHANGELOG.md
623
+ ├── CONTRIBUTING.md
624
+ ├── LICENSE
625
+ ├── package.json
626
+ ├── README.md
627
+ └── SECURITY.md
628
+ ```
629
+
630
+ ### Core module map
631
+
632
+ | Module group | Responsibilities |
633
+ |---|---|
634
+ | Project intelligence | Inspection, code search, architecture maps, dependency graphs and impact |
635
+ | Quality and risk | Quality audits, health snapshots, engineering risk and change intelligence |
636
+ | Agent system | Agent registry, workspace context, skills, hooks, model routing and orchestration |
637
+ | Run lifecycle | Run persistence, task settlement, approvals, replay, resume and traces |
638
+ | Review lifecycle | Static/AI review, review history, patch validation, approval and staging |
639
+ | Verification | Script discovery, explicit verification, staged verification and history |
640
+ | Sandbox | Container runtime, security profiles, policy, compliance and cleanup audit |
641
+ | Evaluation | Evaluation suites, benchmarks, matrices, regression and experiment history |
642
+ | Agent improvement | Optimization plans, config snapshots, evolution and release gates |
643
+ | Workspace interface | Local dashboard, workspace browser and bounded MCP tools |
644
+
645
+ ## Security model
646
+
647
+ ANVIL is designed to keep consequential operations explicit and inspectable.
648
+
649
+ - **Local-first by default:** the dashboard runs on loopback and reads the workspace selected by the CLI.
650
+ - **Bounded workspace access:** path resolution rejects traversal and symlinks; readers exclude hidden, generated, dependency and secret-like paths.
651
+ - **Read-only MCP tools:** the MCP server does not expose arbitrary shell execution or workspace writes.
652
+ - **Fail-closed policies:** malformed or unsupported permission policies are not treated as permission grants.
653
+ - **Review before promotion:** patch validation is a dry run; approval records bind to patch and source fingerprints; staging is separate from promotion.
654
+ - **Explicit verification:** the operator chooses which named check to run.
655
+ - **Redacted audit output:** credential-like matches are redacted by the static agent-configuration audit.
656
+ - **Opt-in Docker workflows:** Docker-backed verification and cleanup operations are separate and require explicit operator action.
657
+
658
+ > [!WARNING]
659
+ > ANVIL is an early-stage engineering tool. Local script verification executes project-controlled code on the host; it is **not** an OS sandbox. Docker security depends on the host runtime and selected configuration. Static audits and heuristic risk scores are not security certifications. AI review may send selected source excerpts to the provider you configure.
660
+
661
+ Read [SECURITY.md](SECURITY.md) before using ANVIL with untrusted repositories, agent instructions or project scripts.
662
+
663
+ ## Current capabilities and boundaries
664
+
665
+ The v1.0 release establishes the local engineering workbench foundation.
666
+
667
+ | Area | v1.0 status |
668
+ |---|---|
669
+ | CLI and local workspace | Available |
670
+ | Interactive local dashboard | Available |
671
+ | Project/code/dependency intelligence | Available |
672
+ | Agent registry, skills, hooks and orchestration | Available |
673
+ | Review, patch validation and approval records | Available |
674
+ | Verification, regression and history | Available |
675
+ | Evaluation, benchmark and experiment workflows | Available |
676
+ | MCP server with bounded read-only tools | Available |
677
+ | Claude Code CLI provider adapter | Available |
678
+ | OpenAI, Anthropic, Google and Ollama adapters | Available |
679
+ | GitHub composite Action | Available |
680
+ | GitHub App installation and OAuth foundation | Available |
681
+ | Hosted repository scanning through the GitHub App | Not implemented |
682
+ | Hosted automatic pull-request creation | Not implemented |
683
+ | Hosted autonomous coding agents | Not implemented |
684
+ | Native Cursor/VS Code IDE extension | Not shipped |
685
+ | Hosted multi-user dashboard | Not shipped |
686
+
687
+ This table is intentional: a roadmap item is not a shipped feature. The project tracks planned work in the [ANVIL Capability Roadmap](docs/ANVIL-CAPABILITY-ROADMAP.md).
688
+
689
+ ## Roadmap
690
+
691
+ ANVIL's direction is to grow into a complete, local-first agent engineering harness while preserving clear permission boundaries.
692
+
693
+ - **Agent and skill ecosystem:** expand specialist roles, skill packs, compatibility metadata and lifecycle management.
694
+ - **Memory and context:** structured memory layers with provenance, retrieval and retention controls.
695
+ - **Hooks and policy:** more lifecycle events, deterministic policy evaluation and auditable presets.
696
+ - **Planning and execution:** reusable workflows, checkpoints, cancellation and durable recovery.
697
+ - **Quality and verification:** independent review passes, verification profiles and evidence-linked reports.
698
+ - **Security:** broader configuration scanning, supply-chain checks and posture reports.
699
+ - **Integrations:** stable adapter interfaces and a truthful harness compatibility matrix.
700
+ - **Learning loop:** evidence-based lessons and regression-gated, human-approved configuration releases.
701
+ - **Operator experience:** unified setup/doctor/status commands, export/import and migration tools.
702
+
703
+ See [docs/ANVIL-CAPABILITY-ROADMAP.md](docs/ANVIL-CAPABILITY-ROADMAP.md) for the detailed delivery sequence and non-negotiable product rules.
704
+
705
+ ## Development
706
+
707
+ ### Clone and install
708
+
709
+ ```bash
710
+ git clone https://github.com/anvil-workbench/ANVIL.git
711
+ cd ANVIL
712
+ npm ci
713
+ ```
714
+
715
+ ### Quality checks
716
+
717
+ ```bash
718
+ npm run typecheck
719
+ npm test
720
+ npm run build
721
+ ```
722
+
723
+ ### npm scripts
724
+
725
+ | Script | Purpose |
726
+ |---|---|
727
+ | `npm run dev` | Run the TypeScript CLI during development |
728
+ | `npm run build` | Compile TypeScript into `dist/` |
729
+ | `npm run typecheck` | Type-check without emitting files |
730
+ | `npm test` | Run the Vitest test suite |
731
+ | `npm run test:watch` | Run Vitest in watch mode |
732
+ | `npm run mcp` | Start the built MCP server |
733
+
734
+ ### Contributing
735
+
736
+ 1. Open an issue to discuss substantial changes.
737
+ 2. Keep pull requests focused and explain the user problem.
738
+ 3. Add or update tests for behavior changes.
739
+ 4. Document permission and security implications.
740
+ 5. Never commit credentials, tokens, private keys or local workspace data.
741
+ 6. Run type checking, tests and the production build before submitting.
742
+
743
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
744
+
745
+ ## Project history
746
+
747
+ ANVIL's v1.0.5 release brings seamless single-page dashboard execution, rich pre-populated showcase telemetry, automatic port fallback (`4173..4183`), single-command byte-accurate rollback (`anvil undo`), automated test verification gate (`--verify`), Git pre-commit hook automation (`anvil hook install`), framework-aware entrypoint resolution, full multi-language architecture mapping, automated farzi-file scrubbing, code auto-repair, one-command doctor self-healing, the local CLI, engineering intelligence, agent workflows, MCP integration, GitHub Action and GitHub App installation foundation into one versioned product.
748
+
749
+ The project is maintained as an original ANVIL codebase. ECC is a capability and documentation reference; ANVIL maintains its own identity, implementation, data models and roadmap.
750
+
751
+ For release-by-release changes, see [CHANGELOG.md](CHANGELOG.md).
752
+
753
+ ## Project links
754
+
755
+ | Resource | Link |
756
+ |---|---|
757
+ | Product website | [ANVIL.vercel.app](https://ANVIL.vercel.app/) |
758
+ | Get the GitHub App | [Install ANVIL](https://ANVIL.vercel.app/api/github/install) |
759
+ | Source repository | [anvil-workbench/ANVIL](https://github.com/anvil-workbench/ANVIL) |
760
+ | Organization | [ANVIL WORKBENCH](https://github.com/anvil-workbench) |
761
+ | Releases | [GitHub Releases](https://github.com/anvil-workbench/ANVIL/releases) |
762
+ | Issues and bugs | [GitHub Issues](https://github.com/anvil-workbench/ANVIL/issues) |
763
+ | CI and automation | [GitHub Actions](https://github.com/anvil-workbench/ANVIL/actions) |
764
+ | Roadmap | [Capability Roadmap](docs/ANVIL-CAPABILITY-ROADMAP.md) |
765
+ | Changelog | [CHANGELOG.md](CHANGELOG.md) |
766
+ | Provider guide | [docs/providers.md](docs/providers.md) |
767
+ | GitHub App guide | [GitHub App integration](docs/integrations/github-app.md) |
768
+ | Security policy | [SECURITY.md](SECURITY.md) |
769
+ | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
770
+
771
+ ## Support
772
+
773
+ For questions about ANVIL or help with the GitHub App, contact [m.g.atiwari28@gmail.com](mailto:m.g.atiwari28@gmail.com).
774
+
775
+ ## Maintainer
776
+
777
+ **Aditya Tiwari** · [@AdityaaaTiwari](https://github.com/AdityaaaTiwari)
778
+
779
+ ## License
780
+
781
+ ANVIL is open source under the [MIT License](LICENSE).
782
+
783
+ ## Star history
784
+
785
+ <p align="center">
786
+ <a href="https://www.star-history.com/anvil-workbench/ANVIL">
787
+ <picture>
788
+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=anvil-workbench/ANVIL&type=Date&theme=dark" />
789
+ <img src="https://api.star-history.com/svg?repos=anvil-workbench/ANVIL&type=Date" alt="ANVIL GitHub star history" width="100%" />
790
+ </picture>
791
+ </a>
792
+ </p>
793
+