NomadCode

NomadCode is a monorepo for AI-assisted development workflows. It brings together a Go orchestration service, a React/Vite operator console, a Flutter client, shared contract space, and root-level agent-operation rules.

The repository is currently an early product scaffold. The core service owns task orchestration and persistence, the web and mobile apps provide initial operator surfaces, and agent-ops/ keeps the rules and roadmap that AI agents need before changing the workspace.

Current Status

• services/core has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, model/A2A client paths, and Plane/Mattermost adapter stubs.
• apps/web is a React/Vite scaffold for Agent, Projects, and Settings views. Some state and integration status areas are still mocked or stubbed.
• apps/mobile is a Flutter app scaffold with Firebase Messaging, local notifications, and HTTP client dependencies.
• packages/contracts is a placeholder for future shared OpenAPI, protobuf, generated client, fixture, and compatibility assets.
• Active planning lives under agent-ops/roadmap/; this README links to that context instead of duplicating milestone state.

Quick Start

Install only the runtimes needed for the part of the workspace you are using.

# Show service/app dev entrypoints.
bin/dev

# Run workspace checks for installed toolchains.
bin/test
bin/lint
bin/build

Run the core service locally. The scripts provide local defaults, but they still expect reachable PostgreSQL and Redis services; see services/core/README.md for the current code-server database setup notes.

cd services/core
./bin/migrate-up
./bin/run

Run the web console:

cd apps/web
npm install
npm run dev

Run the Flutter app:

cd apps/mobile
flutter pub get
flutter run

Major Commands

Purpose	Command	Notes
Show local dev entrypoints	bin/dev	Prints core, web, and mobile commands.
Test workspace	bin/test	Runs go test ./..., web npm run check or tests if present, and flutter test; skips missing toolchains.
Lint workspace	bin/lint	Runs go vet ./..., web npm run lint --if-present, and flutter analyze --no-fatal-infos; skips missing toolchains.
Build workspace	bin/build	Runs core go build ./..., web npm run build, and flutter build web; skips missing toolchains.
Run core	cd services/core && ./bin/run	Uses local defaults from the core script unless environment variables override them.
Migrate core DB	cd services/core && ./bin/migrate-up	Uses goose against the configured PostgreSQL database.
Test core	cd services/core && ./bin/test	Thin wrapper around go test ./....
Build core binary	cd services/core && ./bin/build	Outputs to .build/nomadcode-core unless OUTPUT is set.
Run web dev server	cd apps/web && npm run dev	Vite development server.
Check web types	cd apps/web && npm run check	TypeScript --noEmit.
Verify web	cd apps/web && npm run verify	Runs type check and production build.
Run mobile tests	cd apps/mobile && flutter test	Flutter test suite.

Structure

Path	Role
services/core/	Go backend for orchestration, persistence, scheduling, HTTP APIs, and external service adapters.
apps/web/	React/Vite operator console and browser-based agent/project workspace UI.
apps/mobile/	Flutter mobile/desktop client and notification integration surface.
packages/contracts/	Future shared API/schema contracts and generated client boundary.
docs/	Architecture and operations notes.
bin/	Root test, lint, build, and dev helper commands.
agent-ops/	Agent rules, domain routing, roadmap, and repeatable task skills.

Work Context

AI agents should start with the root instructions and project rules before changing files:

• AGENTS.md
• agent-ops/rules/project/rules.md
• agent-ops/rules/private/rules.md when present

For workspace-level files such as this README, also check:

• agent-ops/rules/project/domain/workspace-ops/rules.md
• agent-ops/skills/common/create-readme/SKILL.md
• agent-ops/roadmap/current.md

Keep detailed roadmap state in agent-ops/roadmap/ and detailed domain rules in agent-ops/rules/project/domain/. Do not read agent-task/archive/** unless the user explicitly asks for it.

Development Flow

• Prefer the root bin/test, bin/lint, bin/build, and bin/dev entrypoints for whole-workspace work.
• Keep changes scoped to the owning domain rules. Cross-boundary changes should close the contract, service, and client behavior in the same branch when those boundaries move together.
• For core database changes, update services/core/migrations/ and services/core/queries/, then regenerate sqlc output instead of hand-editing generated files under services/core/internal/db/.
• Keep agent-ops/rules/common/** and agent-ops/skills/common/** as framework-synced areas; put project-specific rules under agent-ops/rules/project/**.

Environment Variables

Runtime	Name	Required	Notes
Core	DATABASE_URL	No, with scripts	Core scripts provide local defaults; set it when running the binary directly or using a different PostgreSQL database.
Core	REDIS_URL, REDIS_KEY_PREFIX	No, with scripts	Core scripts provide local defaults for worker/queue state; set them when running outside those scripts.
Core	AUTH_USERNAME, AUTH_PASSWORD	No	AUTH_PASSWORD enables HTTP Basic Auth for /readyz and /api/*.
Core	MODEL_BASE_URL, MODEL_API_KEY, MODEL_NAME, MODEL_CONTEXT_SIZE, MODEL_TIMEOUT_SEC	No	Configure the OpenAI-compatible model endpoint used by worker execution.
Core	A2A_EDGE_URL, A2A_AGENT_URL, A2A_TOKEN, A2A_TIMEOUT_SEC	No	Configure the A2A-compatible agent call path.
Core	MATTERMOST_BASE_URL, MATTERMOST_TOKEN	No	Reserved for Mattermost adapter integration.
Core	PLANE_BASE_URL, PLANE_TOKEN	No	Configure Plane work item lookup, comment, and state update integration.
Web	VITE_NOMADCODE_API_BASE_URL	No	The web client falls back to http://localhost:8080; apps/web/.env.example documents the same local value.

Reference Documents

• docs/monorepo.md
• services/core/README.md
• apps/web/README.md
• apps/mobile/README.md
• packages/contracts/README.md
• agent-ops/roadmap/current.md