Development

For contributors and anyone running AppSec Agent from a git clone.

Clone and setup

git clone <repository-url>
cd appsec-agent
npm install
npm run build

Build output goes to dist/ (compiled JS + copied conf/).

Scripts

Command	Purpose
`npm run build`	Compile TypeScript, copy config, chmod CLI
`npm run clean`	Remove `dist/`
`npm test`	Run all unit and e2e tests
`npm run test:watch`	Jest watch mode
`npm run test:coverage`	Coverage report
`npm run dev`	Run `src/main.ts` via ts-node

Running from source

# Recommended during development (no build)
npx ts-node bin/agent-run.ts -l

# After build (matches published npm bin)
npm run build
node dist/bin/agent-run.js -l

Do not use node bin/agent-run.ts directly — use ts-node or dist/ (see Getting started — Troubleshooting).

Project layout

appsec-agent/
├── bin/agent-run.ts          # CLI entry (TypeScript source)
├── conf/appsec_agent.yaml    # Default role configuration
├── docs/                     # User guides (README links here)
├── e2e/                      # End-to-end tests (*.e2e.test.ts)
├── src/
│   ├── agent_actions.ts      # Agent run methods (library + CLI backend)
│   ├── agent_options.ts      # RoleSpec / Claude Options builders
│   ├── main.ts               # CLI orchestration
│   ├── utils.ts              # YAML, paths, helpers
│   ├── providers/            # Claude + Codex providers, RoleSpec
│   ├── schemas/              # JSON output schemas
│   └── __tests__/            # Unit tests
├── dist/                     # Generated by npm run build
└── package.json

Architecture

Core components

AgentActions — Runs agents via resolveProvider().run(). One instance per request in web apps.
AgentOptions — Builds provider-neutral RoleSpec and Claude-specific Options.
resolveProvider() — Returns ClaudeProvider or CodexProvider from AGENT_PROVIDER.
agent-run — Commander CLI; loads yaml, validates flags, calls main().

Provider abstraction (v3.0.0+)

All roles expose get*RoleSpec() methods. Both providers consume the same RoleSpec:

System prompt, max turns, capabilities, MCP config, output schema
Claude: roleSpecToClaudeOptions() → Claude Agent SDK
Codex: roleSpecToCodexThreadOptions() + roleSpecToCodexClientOptions() → @openai/codex-sdk

Structured JSON outputs are validated in src/providers/structured_output.ts.

Testing

npm test

npm test -- agent-run.test.ts

npm test -- --testPathPattern=pr_adversary_codex

Test layout

Location	Type
`src/__tests__/`	Unit tests
`e2e/*.e2e.test.ts`	Integration / wiring tests (mocked LLM)

Codex SDK is mocked in Jest (src/__tests__/mocks/codex_sdk.ts) so CI does not require live OpenAI calls.

API reference (library)

AgentOptions

getToolUsageLog() / clearToolUsageLog()
getSimpleQueryAgentRoleSpec() / getCodeReviewerRoleSpec() / getDiffReviewerRoleSpec() / …
Legacy Claude-only: get*Options() delegates to roleSpecToClaudeOptions()

Path helpers (`utils`)

validateInputFilePath(filePath, baseDir)
validateOutputFilePath(filePath, baseDir)
loadYaml(path, verbose?)
validateDiffContext(data) / formatDiffContextForPrompt(context)

Exports

See src/index.ts for the public package surface published to npm.

Publishing

prepublishOnly runs clean, build, and test. The npm package ships dist/ and conf/ only (see package.json "files").

Configuration
AI Threat Modeler — reference parent-app integration