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.

NomadCode is the development-workflow shell that consumes IOP. It structures user and provider requests into development tasks, tracks project/session/workspace state, and shows execution results to users. It does not own the model runtime, model routing, RAG, MCP policy, or output-validation engine; those responsibilities belong to IOP.

Current Status

• services/core has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, an IOP OpenAI-compatible Responses client path, future A2A agent-delegation scaffolding, and Plane/Mattermost adapter stubs.
• apps/web is a React/Vite scaffold for Agent, Projects, Settings, and browser-based project workspace views. Some state and integration status areas are still mocked or stubbed.
• apps/mobile is a Flutter app scaffold for mobile and desktop client surfaces, 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.

Product Boundary

NomadCode owns the product and workflow layer:

• agent chat, project workspace management, task queue state, and execution status.
• Plane/Jira-style work item intake, provider projection, comments, and status updates.
• user-facing file change, diff, branch, commit, and PR flows.
• desktop and mobile project management surfaces, including project-level desktop windows and mobile top-tab workflows.
• task metadata prepared for IOP calls.

IOP owns the execution and optimization layer:

• OpenAI-compatible model calls, with Responses API support as the current NomadCode integration target.
• local/cloud model routing, model profiles, runtime selection, usage logs, and quality signals.
• CLI agent/runtime adapters such as OpenCode, Aider, Claude Code, Gemini CLI, and Codex CLI.
• RAG, context compression, MCP/tool policy, output validation, retry/fallback, and token/speed/quality optimization.

NomadCode should call IOP through its supported external surfaces. The current NomadCode path is IOP's OpenAI-compatible Responses API. A2A is reserved for later external agent delegation work, and IOP native protocol is not a NomadCode default external call path.

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, project management surface, 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.

IOP boundary work should be checked against the sibling IOP repository when it is available in the same workspace. NomadCode roadmap documents should remain the source of truth for NomadCode product/workflow scope; IOP roadmap documents should remain the source of truth for execution/runtime scope.

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 IOP Edge OpenAI-compatible Responses endpoint used by worker execution. Legacy direct model endpoint compatibility may exist in local scripts, but the target runtime path is IOP.
Core	A2A_EDGE_URL, A2A_AGENT_URL, A2A_TOKEN, A2A_TIMEOUT_SEC	No	Configure the future A2A-compatible agent delegation path. This is not the current default execution 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