Contributing Guide

Contributing Guide

AgentDesk is a TypeScript/React app with a packaged local CLI runtime.

Local Setup

git clone https://github.com/karurikwao/agentdesk.git
cd agentdesk
npm install
npm run dev

Open:

http://127.0.0.1:5173

Useful Scripts

npm run dev
npm run typecheck
npm test
npm run build
npm run test:e2e
npm run smoke:package
npm run verify
npm pack --dry-run --ignore-scripts --json

Use npm run verify before publishing larger changes.

Code Areas

Important areas:

• src/App.tsx: app state, run modes, workflow execution, imports/exports
• src/components: UI panels, canvas, topbar, inspector tabs
• src/lib: run engine, exports, MCP parsing, runtime client, cloud LLM client, redaction helpers
• src/data/workflows: bundled demo workflows
• bin/agentdesk.mjs: packaged CLI and loopback runtime
• tests/e2e: Playwright browser regressions
• docs: launch docs, examples, release notes, screenshots

Contribution Types

Good contribution paths:

• improve docs and setup clarity
• add framework examples
• add parser tests for replay sessions or MCP configs
• improve graph validation rules
• improve artifact viewers
• improve accessibility and keyboard flows
• add safer runtime diagnostics
• add launch/demo examples

Avoid large rewrites unless the issue requires it. AgentDesk is small by design.

Testing Expectations

For docs-only changes:

npm run check:release

For UI changes:

npm run typecheck
npm test
npm run build
npm run test:e2e

For runtime or package changes:

npm run smoke:package
npm pack --dry-run --ignore-scripts --json

For MCP/runtime changes, verify default SDK behavior and legacy fallback where relevant.

Pull Request Expectations

A good PR should include:

• what changed
• why it changed
• screenshots or GIFs for UI changes
• tests run
• known limitations
• security implications if runtime, MCP, cloud, or export behavior changed

Good First Issues

Check:

• https://github.com/karurikwao/agentdesk/issues
• docs/GOOD_FIRST_ISSUES.md

If no issues are open, use Discussions to propose a small scoped improvement before starting.