software-mansion__argent/CONTRIBUTING.md

Contributing to Argent

Thank you for your interest in contributing to Argent! This guide covers everything you need to get started.

Table of contents

• Requirements
• Setting up the dev environment
• Project structure
• Building
• Running the project
• Running tests
• Code style
• Submitting a pull request

---

Requirements

• macOS with Xcode installed (required for xcrun simctl and iOS simulator support)
• Node.js 20.19+ (the lint toolchain's floor; the published package needs 20.12+)
• The simulator-server and ax-service binaries in packages/native-devtools-ios/bin/ (arm64 macOS, installed separately via npx @swmansion/argent install)

---

Setting up the dev environment

1. Fork and clone the repository:

   git clone https://github.com/software-mansion/argent.git
   cd argent
   

2. Install dependencies (npm workspaces installs all packages at once):

   npm install
   

3. Start the dev environment:

   npm run dev
   

   This builds the native devtools dylibs (if the private submodule is available, otherwise uses pre-built binaries), compiles the MCP TypeScript, patches ~/.claude.json to point at the local MCP, and starts the tool-server from source via ts-node. Press Ctrl+C to stop — the script automatically restores your global Argent configuration.

   To use a different port:

   PORT=4000 npm run dev
   

   Note: packages/argent-private is a private git submodule that holds the ObjC source for the native devtools dylibs. If you don't have SSH access to it, npm run dev will use the pre-built dylibs committed to the repository — everything else works normally.

That's it, no separate install steps per package are needed, except packages/docs. It is excluded from the workspace glob and keeps its own lockfile, so npm run lint from the root needs npm install run inside packages/docs first.

---

Project structure

This is an npm workspaces monorepo. All packages live under packages/:

Package	Path	Purpose
@argent/registry	packages/registry	Core library: dependency-aware service lifecycle, blueprints, tools, URNs
@argent/tool-server	packages/tool-server	HTTP API over the registry (port 3001). Registers all blueprints and tools
@swmansion/argent	packages/argent	Published bin shell — minimal dispatcher + bundled subcommands + native runtime assets
@argent/tools-client	packages/argent-tools-client	HTTP client + tool-server launcher shared by @argent/mcp and @argent/cli
@argent/mcp	packages/argent-mcp	MCP stdio protocol adapter — proxies Claude/Cursor calls to the tool-server
@argent/cli	packages/argent-cli	Shell CLI commands: argent run, argent tools, argent server, argent enable, argent disable, argent flags
@argent/installer	packages/argent-installer	Workspace setup logic: argent init, update, uninstall
@argent/skills	packages/skills	Markdown skill files (prefixed argent-*) that instruct AI agents how to use Argent tools
@argent/native-devtools-ios	packages/native-devtools-ios	Pre-built dylibs for iOS simulator injection (view hierarchy, network inspection). ObjC source lives in packages/argent-private (private submodule)

The tsconfig.json at the root uses TypeScript project references; tsconfig.base.json holds shared compiler options (strict, ES2022, etc.).

---

Building

Local development (recommended)

npm run dev

Builds everything and starts the tool-server from source. See Setting up the dev environment for details.

Full build

Build all packages at once using TypeScript project references:

npm run build

To build a specific package:

npm run build -w @argent/registry
npm run build -w @argent/tool-server

To build and bundle the distributable MCP package:

npm run build -w @swmansion/argent
# or, to also produce a .tgz tarball:
npm run pack:mcp

---

Running the project

For day-to-day development, use npm run dev (see Setting up the dev environment).

Production-like start (builds bundles first, then starts from compiled output):

npm run start

This builds the registry, then starts the tools server on port 3001.

Verify the tools server is up:

curl http://localhost:3001/tools

---

Running tests

Tests are written with Vitest. Each package has its own test suite.

Run tests for a specific package:

npm test -w @argent/registry
npm test -w @argent/tool-server

Run tests in watch mode during development:

npm run test:watch -w @argent/registry
npm run test:watch -w @argent/tool-server

---

Code style

• TypeScript strict mode is enabled across all packages ("strict": true in tsconfig.base.json). All code must compile without errors.
• Target: ES2022 with CommonJS modules (except @swmansion/argent which uses ESM).
• Prefer explicit types over any. Use Zod schemas for runtime validation where the codebase already does so.
• Keep commits focused. Prefix commit messages with a type: feat:, fix:, chore:, docs:, refactor:, test:. This feeds the auto-generated changelog on release.

---

Submitting a pull request

1. Create a branch from main with a descriptive name (e.g. feat/add-screenshot-tool, fix/session-leak).
2. Make your changes. Keep the scope of a PR small and focused — it's easier to review.
3. Ensure the build passes:

   npm run build
   

4. Ensure tests pass for the packages you touched.
5. Check for dead code, in a tree with no build output:

   npx tsc --build --clean
   npm run knip
   

   Run it this way round, not straight after step 3. The --max-issues ceiling is counted against an unbuilt tree, because that is what CI analyses; with packages/*/dist present knip finds fewer issues, so a built-tree run carries phantom headroom and can pass locally while the Dead Code job fails. This leaves the tree unbuilt, so run npm run build again before re-running any test suite. If your change legitimately adds an export nothing imports yet, raise the --max-issues number in the same commit rather than deleting someone else's backlog — the bump is the part reviewers should see.
6. Write a clear PR title — it becomes part of the release changelog. Use the same prefix convention as commit messages (feat:, fix:, etc.).
7. Open the PR against main and fill in the description with context on what changed and why.
8. A maintainer will review and may request changes. Address feedback with new commits (don't force-push after review starts).

---

Questions?

If you're unsure about something, open a GitHub Discussion or leave a comment on the relevant issue before spending time on a large change.