What the agent does
The agent clones the package into its own cloud sandbox and reads how it is built and tested before it runs anything. In a library like sindresorhus/ky, package.json is an ESM package whose exports point at ./distribution/index.js and ./distribution/index.d.ts, whose files list ships only distribution, and whose test script chains xo, npm run build, tsc --project tsconfig.test.json and ava; build runs del-cli distribution then tsc --project tsconfig.dist.json, which compiles source/ only. Source lives under source/ with index.ts, a core/ directory, errors/, types/ and utils/; runtime tests under test/ run through ava with tsx as the loader in ava.nodeArguments; type tests under test-d/ are checked by tsconfig.test.json. .github/workflows/main.yml has two jobs on macos-latest: a Node 22, 24 and latest matrix that runs npx ava 'test/**' '!test/browser.ts', and a browser job that installs Playwright and runs the full test script against test/browser.ts. There is no knip configuration and no dead-code check of any kind.
It installs knip as a dev dependency and writes knip.jsonc, with comments, that tells knip what the real entry points are: source/index.ts for the library, every file under test/ and test-d/ as test entries, and distribution/ excluded so compiled output is never counted as source. Then it runs npx knip and reads the report line by line. Some findings are fixes: a helper under source/utils/ that nothing imports gets deleted, an exported type that only its own module uses loses the export, and a dev dependency no file or script references is removed from package.json. Others are configuration: a binary used in a script but not installed, such as np behind the release script when it is not listed in devDependencies, is either added as a dev dependency or put under ignoreBinaries with a comment saying maintainers run it globally. Every exception in knip.jsonc carries a one-line reason, so the file reads as a list of decisions rather than a list of silenced warnings.
Type-only usage is where knip needs the most care in a library, and the agent checks each case against the code. @types/express and @types/busboy are used by test servers under test/, expect-type and @type-challenges/utils only by test-d/, and tsx only through ava.nodeArguments; knip's ava plugin reads that config, so the agent confirms in the report that none of these is wrongly flagged before it touches them. It also runs knip with --production once and records what differs, since a library's consumers only see what exports reaches, and puts that distinction in the pull request rather than enabling production mode blindly.
Finally it wires knip into CI and proves the result. It adds a knip script to package.json and a step to the browser job in main.yml, which already runs the static checks once rather than per Node version, so knip runs once per push and pull request alongside xo. In the sandbox it runs npm install, npx knip to show a clean report, then the repository's own npm test so xo, the build, the type tests and ava all still pass after the deletions. Nothing is removed from source/ without the tests passing afterwards in that same record.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add knip to this TypeScript library. Read package.json, every tsconfig file, the workflow under .github/workflows, and the layout of source, test and test-d first. Add knip as a dev dependency and write knip.jsonc with the library entry from exports, the test and type-test directories as entries, the build output ignored, and a comment on every exception. Run knip, then for each finding either delete the unused file or export, remove the unused dependency, or add a justified exception; check type-only and config-only usages such as the ava loader and type-test helpers against the code before changing them. Add a knip script and a CI step to the job that already runs the static checks once. Run knip until the report is clean, then run the repository's full test script, and open a pull request whose description lists every finding, what was done with it and why, and the command output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request with knip.jsonc, a knip dev dependency and script in package.json, one new step in .github/workflows/main.yml, and the deletions knip justified: files under source/ nothing imported, export keywords on symbols only their own module used, and dev dependencies nothing referenced. The description is a table of every finding with its disposition, fixed or excepted, and the reason.
The run's record keeps the first knip report, the clean one, and the full npm test output after the deletions, so a reviewer can see that xo, the build, tsc --project tsconfig.test.json and ava all passed with the removed code gone. It also keeps the --production run and what it added, so the choice to leave production mode off is a documented one.
Before merging, a reviewer reads the exceptions in knip.jsonc and asks of each whether the reason holds, checks that no deleted export was part of the public surface by looking at source/index.ts, and decides whether the step should block the matrix jobs too or stay in the single static-checks job.
Run it on every repository ready for a dead-code check
A developer who has just finished a feature hands this off from the terminal: one POST /o/{org}/sessions with this body and their package in resources, and the review of what knip found happens on the pull request instead of in a local shell. A platform team that owns many packages sends one request per repository, each with its own exports, test layout and knip report, and each run works in its own sandbox.
To start one run per repository from a script, send a request_id that is a UUID v5 of the repository name with each body, so a retried script returns the run it already started rather than opening a second pull request. The key's webhook_url reports every run the key starts when it finishes, with the pull request in result.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Knip's first run on a mature package is noisy, and the work is in the triage: deciding which of forty findings are dead code, which are type-only usages the tool cannot see, and which are tooling that lives outside package.json. Doing that in a sandbox with the tests run after every deletion is what makes the pull request safe to read, because each removal arrives with the proof that xo, the build and ava still pass, not with a promise.
The same body runs across every library an organisation publishes, and each pull request keeps the full record of the knip reports and the test runs. A maintainer compares the before and after reports, reads the reasons on the exceptions, and merges a dead-code sweep they did not have to perform by hand.
Frequently asked questions
Will knip delete something the public API needs?
Not without a test failing first. The library entry is source/index.ts, taken from exports, so anything that file re-exports counts as used. An export knip flags is one no entry reaches, and the pull request lists each deletion so a reviewer can check it against the public surface before merging.
What about dependencies only tests or type tests use?
They stay. With test/ and test-d/ listed as entries, imports in those files count, and knip's ava plugin reads ava.nodeArguments, so a loader like tsx is seen too. The agent confirms each type-only package against the code before accepting the report.
Why knip.jsonc and not knip.json?
Because every exception should say why it exists, and .jsonc allows comments. A silenced warning with no reason becomes permanent; one with a comment can be revisited when the tooling changes.
Does the step run on every Node version in the matrix?
No. The workflow already runs linting and the build once in a separate job because they do not depend on the Node version, and knip is the same kind of check, so it goes there. Running it three more times would add minutes and no information.
Is production mode turned on?
Not by default. knip --production ignores test files and dev dependencies to show only what consumers reach, which is a stricter question. The agent runs it once, reports the difference in the pull request, and leaves enabling it as a documented follow-up for the maintainers.