Contributing to AgentCanvas

AgentCanvas is a visual agent-design platform for embodied AI research — you prototype agents by drawing node graphs that run in real time against simulators (Habitat-Sim, MatterSim, SAPIEN/ManiSkill2, MuJoCo/robosuite) or real hardware. There are two ways to contribute: content — write a nodeset or compose a graph out of nodesets — and core — improve the framework itself (UI, backend, features, refactors).

§1Content — nodesets & graphs (most contributions)

This is where most research lands: you extend what AgentCanvas can do, without touching the framework.

Write a nodeset — a self-contained capability others can drop into a graph. Two flavors:

Tool nodesets turn a capability into nodes — e.g. a real-time 3D Gaussian-Splatting reconstructor, a voxel-based SLAM system, an object detector, or a new simulator.
Method nodesets encode an agent's reasoning — e.g. a NavGPT nodeset, a MapGPT nodeset.

Or compose a graph — a JSON that wires existing nodesets into a complete agent method. Often no new Python: the contribution is the topology that turns a pile of nodes into a strong graph agent.

How: open a PR adding your files under workspace/ (nodesets/, nodes/, or graphs/). Review is light — it loads, follows the component conventions, and stays inside workspace/. Start from workspace/nodesets/common/example.py for a nodeset, or an existing file under workspace/graphs/ for a graph; the nodeset docs catalog what already exists.

You keep the credit. Every nodeset and graph is attributed to its author/maintainer on the Credits board — maintained in the README and a dedicated doc-site page — so contributing here, rather than in a separate repo, doesn't cost you authorship. If your contribution has an associated paper, its citation link goes on the Credits board too. Your contribution also keeps its own license and copyright: the framework's Apache-2.0 license (the LICENSE file at the repo root) covers the framework, not the plugins — plugin authors choose their own license and retain full authorship.

§2Core — UI, backend, framework (also welcome)

Suggestions, new features, and even refactors of the core (agentcanvas/backend/app/, agentcanvas/frontend/, docs/) are all welcome — the core isn't closed.

One ask: if a change is big enough to cost real time, open a GitHub Discussion first and talk it through before you build. A few minutes aligning up front beats sinking days into something that turns out not to fit. Small fixes and self-contained features can go straight to a PR.

Two hard constraints any core PR must respect:

Import boundary: agentcanvas/backend/app/ never imports domain libraries (habitat, habitat_sim, vlnce_baselines, habitat_baselines) — those live in workspace/ (enforced by agentcanvas/backend/app/test_import_boundary.py).
Contract changes need an ADR: touching BaseCanvasNode, BaseNodeSet, PortDef, NodeUIConfig, ConfigField, DisplayField, or wire types affects every nodeset author, so it goes through an ADR.

§3Dev loop & checks

For the full install flow (conda envs, submodules, data), read the Installation guide. Once installed, the minimal dev loop is:

# Activate the agentcanvas env (Python 3.10+, ADR-platform-004)
conda activate agentcanvas

# Start the canvas (backend :8000 + frontend :5173)
cd agentcanvas && bash run_dev.sh

# Doc-site on :8092 (live reload via SSE)
bash docs/run_dev.sh

Install pre-commit once after clone, then run the full check set before you push:

pip install pre-commit && pre-commit install
pre-commit install --hook-type commit-msg # enable the Conventional-Commits check (§4)

pre-commit run --all-files — whitespace, EOF newline, YAML/JSON validity, file-size limit
Backend + import boundary: cd agentcanvas/backend && python -m pytest
Backend smoke: cd agentcanvas && bash run_dev.sh — server starts and /docs loads
Frontend: cd agentcanvas/frontend && npm run build (or npm run typecheck)
Docs: no build step — open the page in bash docs/run_dev.sh (:8092) and confirm it renders

§4Git conventions & PR format

Commits follow Conventional Commits: type(scope): description.

Type (required) — one of: feat, fix, refactor, docs, chore, test, ci, perf.
Scope (optional) — one of: backend, frontend, eval, orchestrator, data, infra.
Description — lowercase, imperative mood, max 72 characters.

feat(backend): add state container system
fix(frontend): correct edge rendering on zoom
docs(infra): update architecture diagram
refactor(backend): simplify graph executor loop

Enforcement The conventional-pre-commit hook validates the subject line at commit time, but only after you enable the commit-msg stage — pre-commit install --hook-type commit-msg (§3). The full hook suite lives in .pre-commit-config.yaml at the repo root; the accepted types are exactly the list above.

Branches: branch from main, named after the change type: feat|fix|refactor|docs/<short-desc>.

PRs: keep one concern per PR; PR titles follow the same type(scope): description convention as commits. The style rules live in .claude/standard/ — read the one for your task before writing code.

## Summary
- What changed and why (1–3 bullets)

## Reference
Closes #N, or links the Discussion this was agreed in

## Test plan
- [ ] How you verified it works (pytest / npm run build output)

§5Getting help

Roadmap: Roadmap
Talk before a big change: GitHub Discussions
Who built what (+ citations): Credits (doc-site) · README
What nodesets already exist: Nodeset docs
Glossary: glossary — read before touching canvas / graph / state features
Design rationale: Architecture Decisions — ADRs grouped by field
Issues: github.com/jianzhou0420/AgentCanvas/issues