About Agent-HAnS
Agent-HAnS is a tool, presented in an ASE 2026 paper, that lets an AI coding agent keep track of a codebase's features as it builds it, automatically. A feature here just means a piece of functionality a user cares about, such as “search papers” or “import BibTeX.” As the agent adds, changes, or removes functionality, Agent-HAnS instructs it to update a feature model, a simple tree of everything the app can do, and to leave small markers directly in the code, called embedded feature annotations, recording exactly which feature each file, folder, or block of code belongs to. Normally a developer has to do this by hand, and it goes stale as the code changes. Agent-HAnS makes the agent do it as a normal part of writing code, with no extra effort from the developer.
Under the hood, Agent-HAnS plugs into the coding agent through the Model Context Protocol and adds a project instruction file, two agent skills for updating the model and writing annotations, and a small server. That server also drives a live dashboard, so after every prompt a developer can see exactly what changed at the feature level, not just which files changed, before deciding what to ask for next. Since an agent can't be trusted to get the model or the annotations right every time, that dashboard is the human-in-the-loop check on the automation, and this audit page is us doing that check by hand after the fact. Agent-HAnS itself is open source: github.com/isselab/Agent-HAnS.
About this artifact
This repository is the companion artifact for the Agent-HAnS paper. It contains ReferenceManager, a demo web API built entirely by an AI coding agent running Agent-HAnS; the full transcript of every prompt and agent response that built it; and a manual audit of how accurate the automatically generated feature model and annotations turned out to be. The app was built through 10 evolution steps, each one a single structural change to its feature set (for example, merging two features into one), driven by 1–6 natural-language prompts to Claude Code. Every feature and every annotation described below was produced by the agent, not by a human.
The demo app
ReferenceManager is a web API for managing research paper references, built with .NET 9, Entity Framework Core, and SQLite, plus a single-file browser frontend (ReferenceManagerUI/index.html) for interacting with it. Between the two, it supports full CRUD for papers, authors, and groups; full-text search over papers; and BibTeX import/export. Both pieces were built entirely through agentic coding using Claude Code, no line was hand-written.
Build and run
cd ReferenceManager
dotnet run
# API + Scalar UI at http://localhost:5062/scalar/v1
Then open ReferenceManagerUI/index.html directly in a browser, no build step or Node.js required, to use the app.
Development history
demonstration/ holds one verbatim Claude Code session per evolution step, showing the developer prompt, the agent's tool calls, and the automatic feature model update after each cycle. The table below lists all 10 steps: what changed in the feature model, whether it was an addition, a merge, a split, or a removal, the commit each step starts at, and how much code it touched.
| Ev. | Feature model change | Type | Starts at | Change size |
|---|---|---|---|---|
| 1 | Database, ApiDocs, Papers | Add | ed21380 | +157 |
| 2 | Collections, Versioning | Add | b45824a | −75 +776 |
| 3 | Tags | Add | e6688f4 | +115 |
| 4 | Favorites | Add | 17b8b03 | +40 |
| 5 | Tags + Collections → Groups | Merge | db3b9fa | −388 +287 |
| 6 | Papers.ImportBibTex | Add | d189e0c | +395 |
| 7 | Papers.ExportBibTex | Add | 2857c5a | −5 +111 |
| 8 | Papers.Authors → Authors | Split | 975d7a4 | −119 +474 |
| 9 | Papers.SearchPapers | Add | f91dc28 | −10 +112 |
| 10 | − Favorites | Remove | ba1919f | −45 +1 |
demonstration/prompts.md lists all 27 developer prompts. demonstration/result-stats.md reports final cloc statistics. Full history, mapped commit-by-commit to each step, is on the History page.
Annotation audit
Agent-HAnS writes annotations automatically, but it can get them wrong, for example by leaving a marker pointing at a feature that was later removed. We manually went through every single annotation the agent produced in the final codebase and checked whether it is actually correct. The full audit report shows exactly what we checked and what we found.
License
Source code in ReferenceManager/ and ReferenceManagerUI/ is licensed under the MIT License. Everything else, demonstration/, this README, annotation-audit.html, and this site, is licensed under CC BY 4.0.