BlackAgents

---

A local-first manager for AI agent artifacts — agents, commands, rules, and skills — with a graphical UI. BlackAgents reads and writes the real .md / .mdc files in a project folder on your machine, uses an editable authoring-standards baseline to guide creation, and visualizes how artifacts reference each other in an Obsidian-style relationship graph.

Agents can also act on that folder: they read files, call MCP tools, and — only after you approve — write files or run commands. You can line agents up into workflows, and a second brain turns your feedback into notes you approve before they are saved.

Features

• Workspace Studio & Domain Templates — create fresh workspaces from scratch with built-in starter kits (Crypto Assets Hub, Software Engineering, or Blank), or open existing project folders on disk.
• Artifact CRUD — create, edit, rename, and delete agents, commands, rules, and skills with a Markdown editor (live preview) and type-aware frontmatter fields.
• @ mentions — type @ in a body to pick another artifact by type. On save, the token becomes the markdown link the graph understands.
• Authoring standards — an editable, per-workspace standards baseline that drives inline hints (required sections, anti-patterns) as you write.
• Guided wizard — a Type → Details → Body → Review flow for creating artifacts.
• Draft and review in the editor — Draft with assistant writes a new body from the name and description. Validate with assistant reviews a draft or an existing artifact against the standards and lists findings. It does not rewrite the file.
• YouTube as a source — paste a YouTube link in the assistant, or on Skills → New. BlackAgents reads the captions and the assistant uses that text. A new skill can be drafted from the videos, and the saved body keeps a Sources section. If a video has no captions, paste the transcript.
• Relationship graph — an Obsidian-style force-directed graph of the cross-references between artifacts.
• Multi-platform export — re-emit a workspace's artifacts in another platform's layout (.cursor / .claude / .windsurf / .agents) with a per-file diff (create / overwrite / unchanged), a cross-repo target folder, and a .zip download.
• Drift / sync view — a read-only, per-platform report of which on-disk files are in-sync, drifted, or missing (semantic comparison, so cosmetic re-serialization isn't flagged).
• Chat with agent personas — talk to any agent in the active workspace. It runs with that agent's persona, linked skills and rules, and memory notes. Attach text, images, and PDFs, or add a YouTube link. The microphone fills the message from your voice. You still press Send.
• Models by task — in Settings → AI, pick a model for Voice, Vision, Fast, and Reasoning. An agent or a workflow step can use one of those jobs, or its own model. The most specific choice wins: step, then agent, then workflow, then the assistant default.
• Agent tools and approvals — the assistant can list, read, and write workspace files. A file write asks you to deny it, allow it for that message, or allow it for the chat. Settings → AI can allow file writes with no ask. Commands still ask.
• Artifact bundles — ask the assistant for a team and it proposes one agent plus up to three skills and three rules. Create all saves them after a standards check.
• Workflows — a local production line. Each step runs one workspace agent and passes its result to the next. Run by hand, on an interval, or daily while the app is open.
• Second brain — thumbs up or down on a chat reply or a finished run. BlackAgents may draft a memory note, skill, or rule. Nothing is saved until you approve it on Brain.
• Jev (optional) — a fast classifier for small choices: which artifact to load, which skill fits a task, whether a skill description is too wide, whether a workflow step should continue, whether a scheduled run is needed, and what is worth learning. The app still works with Jev off.
• Model Context Protocol (MCP) — configure servers per workspace in Settings → MCP Servers (stored in .black-agents/mcp.json). A server can be a local command, HTTP, or SSE. HTTP and SSE can send headers, such as Authorization. Each server is trusted, ask, or risky. Chat shows a trace for every tool call.
• Assistant drafting (bring your own key) — describe an artifact in plain language and the assistant proposes a standards-compliant draft you can open straight in the editor. Keys are stored locally (0600) and never leave your machine.

Concepts

Type	Purpose	File
Command	Orchestration layer — sequences agents.	.cursor/commands/<name>.md
Agent	Single-responsibility worker with a persona.	.cursor/agents/<name>.md
Rule	Short declarative guardrail (auto/glob applied).	.cursor/rules/<name>.mdc
Skill	Deep reference package with supporting files.	.cursor/skills/<name>/SKILL.md

Cross-references between artifacts (a command invoking an agent, an agent reading a skill, etc.) are detected automatically and rendered as a graph.

The internal model is platform-agnostic, so the same artifacts can be exported to other tools' layouts:

Platform	Root	Notes
Cursor	.cursor/	Source of truth; rules use .mdc + alwaysApply / globs.
Claude	.claude/	Keeps name + description; no rule-activation keys.
Windsurf	.windsurf/	Maps rule activation onto trigger; commands become workflows.
Antigravity	.agents/	Keeps name + description; rules keep alwaysApply / globs; commands become workflows.

Tech stack

• Next.js 16 (App Router) + React 19 + TypeScript
• Model Context Protocol (MCP): @modelcontextprotocol/sdk (stdio, streamable HTTP, and SSE)
• Jev (optional): @typesafe-ai/sdk, used only by the decision layer
• Electron for the desktop shell
• Tailwind CSS 3.4 + shadcn/ui (Radix + CVA) + next-themes
• gray-matter + fast-glob for artifact parsing
• react-force-graph-2d for the relationship graph
• CodeMirror for the markdown body editor
• zod for input validation, jszip for the .zip export
• Vitest for unit and route integration tests, Playwright for end-to-end flows
• Persistence: the local filesystem (your workspace). App settings live in ~/.black-agents/ (config.json, settings.json, and secrets.json for keys, written 0600). Per-workspace workflows, brain notes, MCP servers, and MCP trust live in <workspace>/.black-agents/.

Model Context Protocol (MCP)

BlackAgents provides first-class support for the Model Context Protocol (MCP), allowing agents in any workspace to autonomously connect to external tools, databases, APIs, and execution environments.

Configuration (.black-agents/mcp.json)

MCP servers are configured per-workspace in .black-agents/mcp.json (BlackAgents owns this file). A legacy .cursor/mcp.json is migrated automatically on first read if the BlackAgents file is missing.

{
  "mcpServers": {
    "sqlite-db": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data.db"],
      "env": {}
    },
    "market-feed": {
      "url": "https://mcp.example.com/sse",
      "transport": "sse"
    },
    "docs-api": {
      "url": "https://example.com/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "${secret:mcp.docs-api.header.Authorization}"
      }
    }
  }
}

Auth tokens entered in Settings → MCP Servers are stored in ~/.black-agents/secrets.json (mode 0600). The workspace file keeps only ${secret:…} placeholders so tokens are not committed. BlackAgents resolves them when connecting. If you also use Cursor’s MCP panel, configure that separately (Cursor does not read .black-agents/mcp.json).

Key Capabilities

• Transports: a local command (npx, uvx, python, node), streamable HTTP (POST), or SSE. A URL with no transport is treated as HTTP. HTTP and SSE send resolved headers (including secret-backed bearer tokens).
• Autonomous Tool Execution: When chatting with an agent persona (e.g. portfolio-rebalancer), the agent discovers available tools from enabled servers and can call them inside a bounded loop (8 turns by default, up to 20 in Settings → AI).
• Trust: each server is trusted (treated as a read), ask (needs approval, the default), or risky (needs approval every time). The choice is stored in .black-agents/mcp-policy.json.
• Settings & Tool Diagnostics: Navigate to Settings → MCP Servers to view live connection statuses (Connected / Error / Disabled), inspect tool signatures, test server responsiveness with timeout boundaries, or add new servers.
• Visual Execution Traces: In the Assistant chat, assistant responses display collapsible execution trace cards showing tool name, arguments, elapsed duration in milliseconds, and structured JSON results or errors.

Browser automation (desktop)

Electron only (npm run desktop:dev / packaged app). Settings → Browser enables Playwright MCP (@playwright/mcp) with a persistent Chromium profile. Teach a site by recording (Settings) or coaching in chat, then Save as browser flow. Replay with the builtin browser_run_flow tool or the time-registrar agent. Install Chromium once with npm run desktop:install-browser.

Flows store an intent per step. Replay is deterministic-first, then LLM self-heal (Fast/Reasoning model + a11y snapshot) on selector failures, optional assert steps, secret-aware fills (browser.* in secrets.json), and a local action cache under .black-agents/browser-cache/. Toggle Update flows on heal in Settings → Browser (default off).

Workspace Starter Kits

When creating a new workspace in Settings or the header menu, you can start from scratch or choose a domain template:

• Crypto Assets Hub (crypto):
  • portfolio-rebalancer agent — computes portfolio drift, target rebalancing, and DCA actions.
  • risk-management.mdc rule — enforces non-negotiable concentration limits (max 40% non-BTC/ETH, max 5% microcaps, 10% cash buffer).
  • defi-lending-protocols skill — guides health factor thresholds and borrow/supply rate mechanics (Aave, Morpho).
  • weekly-portfolio-review command — orchestrates weekly audits across wallets and agents.
  • .black-agents/mcp.json — preconfigured MCP server for external market data tools.
• Software Engineering (software):
  • feature-developer agent — plans, writes, and tests production code.
  • typescript-strict.mdc rule — enforces strict typing, error handling, and lint rules.
  • testing-patterns skill — testing strategies with Vitest and testing library.
• Blank Workspace (blank):
  • Clean directory scaffold ready for custom agent setups.

Getting started

npm install
npm run dev

Open http://localhost:3000 to initialize a new workspace using a starter kit (like Crypto Assets Hub or Software Engineering) or open an existing project folder from your disk. You can switch or manage workspaces at any time from the header.

Desktop app (Electron)

Run the Next.js development server inside an Electron window:

npm run desktop:dev

Build an unpacked desktop application for local testing:

npm run desktop:dir

Create distributable installers for the current operating system:

npm run desktop:pack

The packaged app starts a private Next.js standalone server on an available loopback port. It keeps the same local workspace and ~/.black-agents configuration as the browser version. Distributables are written to dist-electron/. macOS packages are unsigned until signing credentials are configured.

Minimizing the window hides it and leaves a menu-bar icon. Click the icon to open the window again. Right-click it for Open and Quit. The app stays in the Dock. The red close button still closes the window.

Using the chat assistant & agent personas

1. Go to AI Providers and configure credentials for OpenAI, Anthropic, or a Custom OpenAI-compatible endpoint (e.g. OpenRouter, or a local Ollama / LM Studio server). Keys are stored locally at ~/.black-agents/secrets.json with 0600 permissions.
2. Drafting artifacts: Open Assistant and describe a new artifact, or name an existing one to update it. A new draft opens in the editor. An existing name opens that artifact with the new text, or Update all saves a bundle over the current files.
3. Chatting with workspace agents: In Assistant, select an agent from the persona dropdown (e.g. portfolio-rebalancer or feature-developer). Type @ to pick an artifact from the workspace. The chat loads it into the turn and shows it as a Context badge. /name also works when that name belongs to only one artifact.
4. Approvals: a file write shows a card. Deny it, allow it for that message, or allow it for the chat. A command still asks every time. Settings → AI → Allow file writes without asking skips the file-write card. Turning that on shows a warning.
5. Files, voice, and YouTube: attach a text file, image, or PDF, or paste a YouTube link. The assistant reads captions, not the picture. Use the microphone to fill the message. On Skills → New, add the same links and draft the skill from them.
6. MCP tools: Configure MCP servers in Settings → MCP Servers (or edit .black-agents/mcp.json directly) and set each server's trust. For HTTP or SSE, add headers when the server needs a token. Active tools are discovered when you chat.
7. Workflows: open Workflows, add steps that point at workspace agents, then run the line. A live run page shows each step, waiting approvals, and files changed. Interval and daily runs fire only while the app is open. In the assistant, /workflow-name starts a saved workflow.
8. Brain: rate a reply or a finished run. Open Brain to approve or reject the proposed note, skill, or rule. Approved notes are added to later chats with that agent.
9. Jev (optional): in Settings → AI, turn on Use Jev, pick a provider, and run Test Jev. With it off, chat, workflows, and learning still run. Models by task on the same screen picks the model for Voice, Vision, Fast, and Reasoning.

Roadmap

Shipped:

• Artifact CRUD, authoring standards, guided wizard, @ mentions, and the relationship graph
• Multi-platform export (diff, .zip, cross-repo target) and the drift / sync view
• Bring-your-own-key assistant, in-editor draft and standards review, agent personas, and artifact bundles
• Agent tool loop with approvals, MCP trust, workflows, second brain, and optional Jev
• Chat files, voice input, YouTube captions, and models by task
• MCP over HTTP and SSE, with request headers
• Workspace starter kits and the Electron desktop app

Still open:

• Token-by-token streaming (chat already streams each model turn over SSE)
• Choosing the default provider and model in the UI
• Draft with assistant inside the wizard and while editing an existing artifact
• Two-way sync that can import artifacts which exist only in .claude
• Scheduled workflows while the app is closed
• Approvals that survive a restart
• Parallel steps inside one workflow

Scripts

Script	Description
npm run dev	Start the dev server
npm run build	Production build
npm run start	Serve the production build
npm test	Vitest unit and integration tests
npm run test:watch	Vitest in watch mode
npm run test:cov	Vitest with coverage for lib/
npm run test:e2e	Playwright end-to-end tests
npm run desktop:dev	Run the application in Electron during development
npm run desktop:dir	Build an unpacked desktop application
npm run desktop:pack	Build desktop installers for the current OS
npm run lint	Lint
npm run type-check	TypeScript check

Desktop releases

A push to main opens a release pull request when there are user-facing changes. Merging that pull request tags the version and builds the desktop installers on GitHub Releases. The installers appear about 5 minutes after the tag.

Use feat: for a new feature and fix: for a bug fix in the commit message. While the app is still 0.x, a feature moves the second number (0.1 to 0.2) and a fix moves the third (0.1.3 to 0.1.4).

The workflow publishes:

System	File
macOS (Apple Silicon)	.dmg and .zip
Windows (64-bit)	installer .exe
Linux (64-bit)	.AppImage

These builds are not code-signed yet. macOS and Windows show a warning the first time you open the app. The release notes explain how to continue.

License

MIT © 2026 Cristofer Domingues