Debugger Visibility Dashboard

The Newnadoon Debugger Visibility Dashboard is the fastest way to see what your agents are doing while you build them.

What it is

The dashboard gives you a visual way to inspect agent execution instead of treating your agent like a black box.

Use it to:

• see which agents are available in your project
• run an agent with real input
• inspect step-by-step execution
• observe tool calls and outputs
• review state changes and runtime events
• validate that your config, prompts, tools, and memory are wired correctly

In simple terms: it is your development control room for agents.

Install the dashboard

The debugger is not part of @newnadoon/ai-framework. Runtime installs stay slim. Add the UI only when you want it:

$ npm install -D @newnadoon/ai-framework-dashboard

create-newnadoon asks this as an optional prompt (default no).

Start the dashboard

Run the dashboard from your project root:

$ npx newnadoon dev

By default, the dashboard runs locally at:

 http://localhost:2024

This starts a separate local server for the debugger UI. Your app does not need to embed the dashboard directly.

Why newnadoon.json is required

The dashboard needs a way to know which agents exist in your project.

That is the job of newnadoon.json.

Think of this file as the manifest for your agent project:

• it tells Newnadoon which agents are registered
• it tells the dashboard where each agent file lives
• it optionally tells the runtime which env file to load

Without newnadoon.json, the dashboard has nothing to load, so it cannot render your available agents.

Minimal newnadoon.json

Create this file in your project root:

{
  "agents": {
    "general-department-agent": {
      "name": "General Department Agent",
      "path": "./agent.ts"
    },
    "customer-success-department-agent": {
      "name": "Department Routing Example Agent",
      "path": "./agent-customer-success.ts"
    }
  }
}

What each field means

agents

This is the list of registered agents the dashboard can show.

Each key inside agents is the internal agent id.

name

This is the human-friendly label shown in the dashboard UI.

path

This points to the file that exports your agent.

Newnadoon resolves this path relative to your project root. In scaffolded projects, it can also resolve aliases such as @agents/... and @dashboard/....

env (optional)

You can also include an env file path if you want the runtime to load environment variables automatically:

{
  "agents": {
    "staff-agent-simple": {
      "path": "@agents/staff-agent-simple",
      "name": "Staff Agent (Simple)"
    }
  },
  "env": ".env"
}

How the dashboard finds your project

When you run npx newnadoon dev, Newnadoon looks for newnadoon.json starting from your current directory and walking upward until it finds the project root.

That means the most reliable workflow is:

1. open a terminal in your project root
2. make sure newnadoon.json is there
3. run npx newnadoon dev

If needed, you can also point Newnadoon at a project directory explicitly with the NEWNADOON_PROJECT_DIR environment variable.

What happens after startup

Once the dashboard starts:

1. Newnadoon loads newnadoon.json
2. it reads the registered agent ids from agents
3. it loads each agent module from its configured path
4. it renders those agents in the dashboard
5. you can select an agent and run it with test input

This is why the config file matters so much: the dashboard is driven by your registered agents, not by guessing which files might contain agent code.

If you used the CLI scaffolder

If you created your project with:

$ npm create newnadoon@latest

then the CLI already creates newnadoon.json for you and also copies sample agents into your project.

That means you can usually do this right away:

1. open the generated project
2. add your API key to .env or .env.local
3. run npx newnadoon dev
4. open the dashboard and test the sample agents

Common setup pattern

For most teams, the workflow looks like this:

1. create or update an agent file
2. register it in newnadoon.json
3. start the dashboard with npx newnadoon dev
4. run the agent from the UI
5. inspect steps, tool calls, and outputs
6. adjust prompts, tools, memory, or workflow logic
7. repeat until the behavior is correct

Voice agents in the dashboard

Agents registered with a voice: {} marker (such as the sample Voice Assistant) show a Voice panel next to Run Controls.

To use it:

1. Run npx newnadoon-voice setup once in your project.
2. Set NewnaVoiceKit + STT/TTS keys and NEWNAVOICEKIT_AGENT_RUN_URL=http://localhost:2024/api/voice/turn in .env.
3. Start the voice worker: npx newnadoon-voice dev.
4. Keep the dashboard running (npx newnadoon dev).
5. Select [voice] Voice Assistant, click Connect voice, then speak or use Send turn.

Spoken turns appear in the Execution Timeline when the turn API URL is set. Full walkthrough: Voice agents.

Kanban work-item agent

Test the agent in this dashboard before connecting Cursor MCP.

1. From the agent project run npx newnadoon dev.
2. Select Kanban Work Item Agent.
3. Do not put an ndk_ API key in .env. Pass organizationId in the run JSON. The dashboard uses KANBAN_API_URL + LANGGRAPH_INTERNAL_SECRET.
4. Example input:

{
  "task": "list work items in project local blah",
  "organizationId": "<kanban-organization-id>"
}

5. Click Start Run and confirm list_work_items in the timeline.

Cursor MCP comes after this works. MCP uses Authorization: Bearer ndk_... instead of a run-input org id.

Troubleshooting checklist

If the dashboard opens but no agents appear:

• confirm newnadoon.json exists in the project root
• confirm the file contains a valid agents object
• confirm each path points to a real agent file
• confirm each agent file exports a default agent factory or agent instance
• confirm you started the dashboard from the correct project directory

Next step

Once your agent looks correct in the dashboard, continue to API to expose it through runtime endpoints, review CLI for command-line workflows, or add speech with Voice agents.