Agent Dashboard

A local dashboard for people who organize their Codex work into file-based specialist projects. It provides one place to inspect and manage the AGENTS.md files and skills that apply to each project without copying them into a database.

The filesystem remains the source of truth. The dashboard reads the configured files on every refresh and only listens on 127.0.0.1.

Features

• A Global view for ~/.codex/AGENTS.md and user-managed global skills.
• One tab per explicitly configured Codex project or specialist.
• Direct viewing and editing of each project's root AGENTS.md.
• Discovery of local skills under common Codex and agent conventions.
• Installation of a skill from a GitHub folder URL.
• Recoverable skill deletion through the macOS Trash.
• Per-project color themes and icons.
• A small macOS .app launcher for the Dock or Spotlight.
• No database, authentication, analytics, CDN, Electron, or automatic filesystem-wide project discovery.

Built-in .system skills are intentionally hidden from the Global view because they are managed by Codex and cannot be deleted from the dashboard.

Requirements

• macOS 13 or later for the launcher and Trash integration.
• Node.js 22 or later.
• Git for cloning the repository.
• Python 3 only when installing skills from GitHub.
• Codex's built-in skill-installer for GitHub skill installation.

The web dashboard itself can run on other platforms, but its launcher and deletion behavior are currently macOS-specific.

Quick start

git clone https://github.com/antoniolg/development-agent-dashboard.git
cd development-agent-dashboard
npm install
cp config/teams.json config/teams.local.json

Edit config/teams.local.json with your own projects and absolute paths, then start the dashboard:

npm start

Open http://127.0.0.1:4317.

For development with automatic server reloads:

npm run dev

Configure the manifest

The dashboard never scans your home directory or reads Codex's complete internal project state to decide which projects exist. The manifest is the explicit, versionable source of truth.

Copy the public template before customizing it:

cp config/teams.json config/teams.local.json

config/teams.local.json is ignored by Git so personal paths and Codex project IDs are not accidentally published. When that file exists, the dashboard uses it automatically. Without it, the committed config/teams.json template is used.

Example:

{
  "schemaVersion": 1,
  "teams": [
    {
      "codexProjectId": "development",
      "name": "Development",
      "contextPath": "/Users/your-name/Projects",
      "color": "#4F8CFF",
      "icon": "square-terminal"
    },
    {
      "codexProjectId": "content",
      "name": "Content",
      "contextPath": "/Users/your-name/Documents/Content",
      "color": "#A879FF",
      "icon": "palette"
    }
  ]
}

Each team requires:

Field	Meaning
codexProjectId	A stable unique identifier for the saved Codex project. Use its actual ID when known; otherwise a unique stable slug is sufficient for the dashboard.
name	The label shown in the tab and project header. Names must be unique.
contextPath	The absolute filesystem path that defines the project's scope. Tildes and environment variables are not expanded.
color	A six-digit hex color used to theme the selected project, for example #4F8CFF.
icon	A supported Lucide icon name.

Supported project icons:

• square-terminal
• palette
• briefcase-business
• feather
• graduation-cap

Unknown icon names fall back to a generic file icon. Project IDs and names must be unique, and at least one project must be present.

You can also point to a different manifest for a single run:

TEAMS_MANIFEST=/absolute/path/to/teams.json npm start

What the dashboard discovers

Global

• ~/.codex/AGENTS.md
• User-managed skills under ~/.codex/skills/
• User-managed skills under ~/.agents/skills/

If the two global skill paths resolve to the same real directory, entries are deduplicated. Anything below .system/ is hidden.

Per project

For each manifest entry, the dashboard reads only the configured contextPath and looks for:

• <contextPath>/AGENTS.md
• <contextPath>/skills/
• <contextPath>/.agents/skills/
• <contextPath>/.codex/skills/
• <contextPath>/.claude/skills/
• <contextPath>/.cursor/skills/

A nested Git repository does not automatically become another dashboard project. Add another manifest entry if it should have its own tab.

Editing AGENTS.md

Select a project and use Edit in the AGENTS.md pane. Saving requires the exact file version that was originally loaded. If another process changes the file while it is open, the dashboard rejects the save and asks you to reload instead of overwriting external work.

Only AGENTS.md files already present in the current inventory are editable. The manifest and SKILL.md files remain read-only in the source viewer.

Installing skills from GitHub

Open a project or Global, click Install from GitHub, and paste a GitHub folder URL:

https://github.com/<owner>/<repository>/tree/<ref>/<path-to-skill>

The selected destination is always shown before installation:

• Global: ~/.codex/skills and ~/.agents/skills. Identical real directories are deduplicated.
• Project: <contextPath>/.agents/skills.

The dashboard delegates installation to Codex's local skill-installer, invokes it without a shell, rejects non-GitHub URLs, and refuses to overwrite an existing skill. A newly installed skill is available to Codex on the next turn.

By default the helper is expected at:

~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py

Use SKILL_INSTALLER_SCRIPT to provide another absolute helper path.

Deleting skills

The delete button moves the exact registered skill folder to the macOS Trash after confirmation. For a registered symbolic link, the link is moved rather than its target repository. System skills are never exposed for deletion.

macOS launcher

Install the reproducible launcher:

npm run launcher:install

This creates ~/Applications/Agent Dashboard.app. Opening it:

1. Checks http://127.0.0.1:4317/api/inventory.
2. Starts the local Node server in the background only when needed.
3. Waits up to 15 seconds for readiness.
4. Opens the dashboard in the default browser.

Reopening the app does not create duplicate servers. It does not install a Login Item or start at login.

Runtime files:

• PID: ~/Library/Application Support/Agent Dashboard/server.pid
• Launcher log: ~/Library/Logs/Agent Dashboard/launcher.log
• Server log: ~/Library/Logs/Agent Dashboard/server.log

Stop only the launcher-managed server with:

npm run launcher:stop

Configuration reference

Variable	Default	Purpose
PORT	4317	Loopback HTTP port.
TEAMS_MANIFEST	config/teams.local.json, then config/teams.json	Override the manifest path.
SKILL_INSTALLER_SCRIPT	Codex's built-in installer path	Override the GitHub installer helper.

The server always binds to 127.0.0.1; changing PORT does not expose it to the network.

Security model

• Loopback-only HTTP server.
• Same-origin checks on mutating API requests.
• No remote project discovery or arbitrary command execution.
• GitHub installs accept only https://github.com/.../tree/... folder URLs.
• Source URLs use opaque IDs instead of filesystem paths.
• AGENTS.md writes use optimistic concurrency.
• Skill deletion is restricted to the current inventory and uses Trash.

This is a local administrative tool. It intentionally has no authentication because it is not designed to be exposed to a network.

Validation

Run the complete local gate:

npm run check

The suite checks JavaScript syntax, shell syntax, manifest boundaries, editor concurrency, launcher installation, recoverable deletion, GitHub URL validation, install destinations, deduplication, and protection against overwriting unrelated apps or existing skills.

Project structure

config/                 Public manifest template
launcher/               macOS app bundle sources
public/                 Browser UI and static assets
scripts/                Launcher installation and stop scripts
src/                    Filesystem inventory and mutation services
test/                   Node test suite
server.mjs              Loopback HTTP server

Current limitations

• The manifest must be maintained manually.
• Paths must be absolute.
• Skill installation currently accepts GitHub folder URLs only.
• Launcher and Trash behavior are macOS-specific.
• There is no authentication or support for network deployment by design.