NOMOS Agent Toolkit

Build, run, and debug NOMOS agents without leaving VS Code.

Features

`manifest.json` IntelliSense

Full JSON Schema validation for NOMOS agent manifests.

Validation: Get red underlines on missing required fields or invalid types.
Hover: View descriptions for every field (capabilities, settings, mcp_servers, etc.).
Autocomplete: Enum completions for transport, color, variant, integrations, and more.

`@tool` / `@background_tool` / `@batch_tool` Diagnostics

The extension automatically audits all NOMOS-decorated Python functions to ensure they meet SDK requirements for LLM compatibility:

Missing Docstrings: Warns if a tool has no description (on @tool, @background_tool, and @batch_tool).
Parameter Mapping: Ensures every function argument is documented with a :param name: entry. The auto-injected job parameter on @background_tool is correctly skipped.
Return Values: Suggests adding :returns: to help LLMs understand output structure.

Trace Viewer

Run NOMOS: Start Agent from the Command Palette (Ctrl+Shift+P).

Live Timeline: View a real-time stream of turn_start, tool_call, llm_end, and custom @@TRACE@@ events.
Inspect Payloads: Click any event to see the full JSON body in a structured viewer.
Cost Awareness: Filter for cost_ceiling_warning to monitor agent spend in real-time.

Hot-Reload

When an agent is running, saving any .py file triggers an automatic debounced restart. The status bar indicates the current state:

⊘ NOMOS: Idle — no agent running
◉ NOMOS: Live — agent running, watching for changes
↻ NOMOS: Reloading… — file changed, restarting

NomosUI & SDK Snippets

Type nomos- in any Python file to see all 80+ snippets for building agents, rich UIs, and production patterns.

1. Agent Scaffolding

Prefix	Description
`nomos-agent`	Function-style agent scaffold.
`nomos-class-agent`	Class-style `NomosAgent` scaffold with heartbeat.
`nomos-tool`	Synchronous `@tool` decorator.
`nomos-async-tool`	Async `@tool` for I/O-bound work.
`nomos-background-tool`	`@background_tool` with job progress + cancellation.
`nomos-batch-tool`	`@batch_tool` for parallel batch processing.

2. Lifecycle Hooks

Prefix	Description
`nomos-on-install`	First-time setup when agent is installed.
`nomos-on-upgrade`	Migrate state on version upgrade.
`nomos-on-suspend`	Flush caches before agent is paused.
`nomos-on-resume`	Reload state when agent resumes.
`nomos-on-webhook`	Handle inbound HTTP webhook POST.
`nomos-on-file-event`	React to filesystem changes.
`nomos-on-event`	Receive pub/sub events from other agents.
`nomos-on-task`	A2A delegation entry point.

3. Layout & Scaffolding (NomosUI)

Prefix	Description
`nomos-response`	`NomosResponse` + `NomosUI` scaffold.
`nomos-column`	Vertical layout container.
`nomos-row`	Horizontal layout container with gap/align.
`nomos-section`	Titled collapsible section.
`nomos-card`	Container with optional header/footer.
`nomos-tabs`	Tabbed panel with multiple children lists.
`nomos-modal`	Dialog overlay (set `open=True` to show).
`nomos-form`	Container for interactive input fields.
`nomos-divider`	Horizontal divider line.

4. Display Components

Prefix	Description
`nomos-text`	Text with variants (heading, body, code, etc.).
`nomos-markdown`	Rich text component that renders GFM Markdown.
`nomos-badge`	Colored status badge.
`nomos-alert`	Severity-based alert box (info, error, etc.).
`nomos-stat`	Metric display with trend deltas.
`nomos-table`	Structured data table with key/label columns.
`nomos-list`	Bullet or ordered list.
`nomos-progress`	Visual progress bar (0-100).
`nomos-chart-bar`	Bar chart with `series=[{name, values}]`.
`nomos-chart-line`	Line chart with `series=[{name, values}]`.
`nomos-stepper`	Step indicator (read-only progress stepper).
`nomos-calendar`	Monthly event calendar view.
`nomos-kanban`	Drag-and-drop board with column/card mapping.
`nomos-timeline`	Vertical SVG event timeline.
`nomos-tree`	Recursive collapsible tree view.
`nomos-editable-table`	Inline-editable data table with save callback.

5. Interaction & Inputs

Prefix	Description
`nomos-button`	Interactive button with `callback_tool`.
`nomos-button-group`	Inline group of multiple buttons.
`nomos-text-input`	Single-line text field (use in forms).
`nomos-number-input`	Numeric spinner input (use in forms).
`nomos-textarea`	Multi-line text area (use in forms).
`nomos-select`	Dropdown picker (use in forms).
`nomos-multi-select`	Multi-select checkbox list (use in forms).
`nomos-checkbox`	Boolean toggle (use in forms).
`nomos-slider`	Range slider (use in forms).
`nomos-date-picker`	ISO date selector (use in forms).
`nomos-date-range-picker`	ISO date range selector (use in forms).
`nomos-file-upload`	File dropzone with MIME filters.

6. State, Memory & Secrets

Prefix	Description
`nomos-state-set`	Persist key-value data with optional TTL.
`nomos-state-get`	Retrieve persisted data with default fallback.
`nomos-state-update`	Atomic read-modify-write on a state key.
`nomos-metrics-record`	Record time-series metrics with tags.
`nomos-metrics-query`	Aggregate metrics over a time window.
`nomos-team-state`	Shared volatile state across all team agents.
`nomos-job-status`	UI card for monitoring background jobs.
`nomos-memory-store`	Store text in semantic vector memory.
`nomos-memory-search`	Search vector memory by natural language query.
`nomos-vault`	Access secrets via `Vault` (never hardcode keys).

7. Multi-Agent Orchestration (A2A)

Prefix	Description
`nomos-pipeline`	Multi-agent DAG pipeline scaffold.
`nomos-stage`	Single stage for a pipeline.
`nomos-broadcast`	Fan-out: same task to multiple agents.
`nomos-delegate-parallel`	Fan-out: different tasks to different agents.
`nomos-supervisor`	Monitor agent health and fire "down" callbacks.
`nomos-publish-event`	Publish a named event to the gateway event bus.

8. MCP & Triggers

Prefix	Description
`nomos-call-mcp`	Call a tool on a configured MCP server.
`nomos-mcp-stdio`	`manifest.json` stdio MCP server declaration.
`nomos-mcp-sse`	`manifest.json` SSE MCP server declaration.
`nomos-trigger-webhook`	`manifest.json` inbound webhook trigger.
`nomos-trigger-fs-watch`	`manifest.json` filesystem watcher trigger.
`nomos-trigger-agent-event`	`manifest.json` pub/sub event subscription.

9. Error Handling

Prefix	Description
`nomos-catch-llm`	Catch `LLMError` and all subclasses by type.
`nomos-catch-mcp`	Catch `MCPError` and all subclasses by type.
`nomos-catch-a2a`	Catch `A2AError` and all subclasses by type.
`nomos-catch-cost`	Catch `CostCeilingExceeded` (spend limit hit).
`nomos-error-imports`	Import all NOMOS error classes in one block.

10. Testing

Prefix	Description
`nomos-test-harness`	`AgentTestHarness` + `MockLLM` unit test scaffold.
`nomos-test-multi-agent`	`MultiAgentTestHarness` for A2A wiring tests.
`nomos-mock-llm`	`MockLLM` with tool-call and text response sequences.

11. Rich Output & Media

Prefix	Description
`nomos-render-pdf`	Render Markdown to PDF bytes.
`nomos-render-excel`	Export data to multi-sheet `.xlsx`.
`nomos-render-chart-image`	Render chart to PNG data URI.
`nomos-synthesize-speech`	OpenAI TTS → MP3 data URI.
`nomos-generate-image`	DALL-E image → PNG data URI.
`nomos-image`	NomosUI image component.
`nomos-audio-player`	NomosUI audio player component.
`nomos-video`	NomosUI video player component.

12. Computer Use

Prefix	Description
`nomos-cu-click`	Vision-guided click on a UI element.
`nomos-cu-type`	Click field and type text into it.
`nomos-cu-launch`	Launch a desktop application.
`nomos-cu-sequence`	Run a multi-step computer-use macro.
`nomos-cu-manifest`	`manifest.json` computer-use capability block.

Requirements

VS Code 1.85+
Python 3.10+ with the NOMOS SDK (pip install nomos-sdk)
A NOMOS workspace (folder containing manifest.json)

Extension Settings

Setting	Default	Description
`nomos.pythonPath`	`python`	Python interpreter to use (can be a virtualenv path).
`nomos.agentEntryPoint`	`agent.py`	Entry file to run when starting the agent.

Commands

Command	Description
`NOMOS: Start Agent`	Launches the agent and opens the trace viewer.
`NOMOS: Stop Agent`	Safely terminates the running agent.
`NOMOS: Open Trace Viewer`	Shows the event timeline panel.
`NOMOS: Validate Manifest`	Jumps to `manifest.json` for schema checks.

License

MIT

NOMOS Agent Toolkit

Nomos

NOMOS Agent Toolkit

Features

manifest.json IntelliSense

@tool / @background_tool / @batch_tool Diagnostics

Trace Viewer

Hot-Reload

NomosUI & SDK Snippets

1. Agent Scaffolding

2. Lifecycle Hooks

3. Layout & Scaffolding (NomosUI)

4. Display Components

5. Interaction & Inputs

6. State, Memory & Secrets

7. Multi-Agent Orchestration (A2A)

8. MCP & Triggers

9. Error Handling

10. Testing

11. Rich Output & Media

12. Computer Use

Requirements

Extension Settings

Commands

License

`manifest.json` IntelliSense

`@tool` / `@background_tool` / `@batch_tool` Diagnostics