Pointsman

Fast task routing with Jev and dependency DAGs.
_{formerly Jev Router}

English | 한국어 | 简体中文

Pointsman is a Jev-powered task routing project for coding agents. It turns structured decisions into dependency DAGs: divide work, connect prerequisites, and dispatch ready tasks to coding workers. The research runner connects routing decisions to scoped artifacts, public checks and recorded outcomes.

This release provides the Jev client, evaluation tools, run contracts and usage dashboard. See released/research/local capabilities and skill decomposition. The advanced DAG experiments are documented on the research branch.

Measured results · How routing works · Quick start · Documentation · Security

Measured results

In the completed D067 comparison, Jev decomposition plus dependency decisions used 21.84% less development-stage time and 46.50% fewer reported tokens than the structured Claude baseline. Jev decomposition alone used 28.74% less time and 41.42% fewer tokens. All three conditions passed 85 public and 63 independent checks.

OpenAPI Python client generator	Development-stage time	Reported token sum	Historical API-rate-equivalent cost
Claude structured decisions + Claude workers	36m 20.704s	6,772,666	$21.135172
Jev decomposition decisions + Claude workers	25m 54.036s	3,967,289	$9.864863
Jev decomposition and dependency decisions + Claude workers	28m 24.540s	3,623,150	$8.766580

One run per condition in a concurrent cohort; identical Opus 5.5 medium workers and two worker slots per condition. Time includes decisions, implementation, repairs and public validation, excluding shared preparation and independent grading. Token sums include Claude input/output/cache creation/cache reads and Jev input/output; provider tokenizers differ. All three conditions had 57 external adapter calls. Reductions use the Claude row as denominator. The decomposition-plus-relations condition also used 58.52% less historical API-rate-equivalent cost; this is not a subscription bill. Methods, token breakdown and separate decision-stage observation · Public aggregate JSON · Complete experiment record.

D068–D085 follow-up results, actual repairs and repeated runs.

How routing works

The main agent supplies the goal, public specification and artifact contracts. Fixed English questions let Jev judge work decomposition and dependencies. The research runner turns validated decisions into an executable DAG, then dispatches ready work within each worker's file scope.

Goal + specification + artifact contracts
→ structured Jev questions and input validation
→ decomposition and dependency decisions
→ dependency DAG and ready-task queue
→ scoped coding workers
→ public checks tied to artifact revisions
→ recorded outcomes and evidence-driven repair routing

• Dependencies guide dispatch. Ready tasks can run concurrently; downstream work consumes validated upstream artifacts.
• Decisions reach execution. Structured answers connect to worker scopes and execution handlers.
• Evidence follows each decision. Questions, accepted answers, usage, artifact revisions and checks stay connected.

The controller enforces permissions and validation. Jev selects within that contract; tests establish whether the resulting artifacts meet the task requirements. See the technical specification and research state.

Quick start

Requires Node.js 22 or later. There are no external packages.

git clone https://github.com/Kai-Leee/pointsman.git
cd pointsman
npm run mcp:fetch   # pinned jev-mcp binary for the MCP tests, checksum-verified
npm test            # fake key and mock HTTP only; no inference, no balance use
npm run check:links # relative links, heading anchors and research-branch links
npm run eval:demo   # offline evaluation of synthetic records

mcp:fetch supports macOS ARM64, Linux x64 and Linux arm64 (SOURCE.json). Without it, the three MCP tests fail. CI runs the tests on macOS (Node 22) and in Docker (Node 24 and 26).

Connecting to Jev needs a Jev AI account and key, and acceptance of the Jev AI Terms of Use (sign-in):

npm run login            # accept terms, sign in on the key page, paste the key (hidden)
npm run config           # prints settings and whether a key exists; no network
npm run models           # one authenticated GET
npm run demo -- --spend  # one paid POST; uses your Jev balance

More: all usage, failure handling and deployment · MCP launcher · dashboard (npm run dashboard) · benchmarks.

Documentation

main holds code, run contracts and usage documents. Experiments, decisions and logs live on the research branch.

• Start here: technical spec · run contracts
• Usage: usage guide · evaluation CLI and input contract · dashboard · paired run and separate Opus monitor · benchmarks · MCP
• Research branch (Korean): current state · document index · decisions · work log · verification · evaluation methods · live experiment feasibility · real-time failure reporting
• Releases: changelog
• Contributors and agents: AGENTS.md (Codex entry) · CLAUDE.md (Claude entry, imports AGENTS.md) · agent roles and handoff

Security

• Keep JEV_AI_API_KEY on the server: a process environment variable or ~/workspace/.env. Set another file path with JEV_AI_ENV_FILE.
• Never put the key in chat, browser code, Git, command-line arguments or logs. Do not use public prefixes such as NEXT_PUBLIC_, VITE_ or PUBLIC_.
• Destination URLs are fixed in src/config.mjs. Redirects are refused. Diagnostic output never prints the key or the Authorization header.

License

Apache License 2.0.

The license covers the code in this repository only. It grants no rights to the Jev AI service. Live Jev features need your own Jev AI account and key, and you must accept the Jev AI Terms of Use and Privacy Policy.

The reused jev-mcp v0.3.1 binary is Apache-2.0 and is not committed. Its source and checksums are in vendor/jev-mcp/SOURCE.json.