Write, read, or resolve handoff notes between agents.

Notes persist locally (JSON) until resolved.

Args: action: write (leave a note), read (fetch open notes addressed to to), or resolve (close a note by id). to: Recipient — an agent or context name (e.g. "frontend-agent"). message: Note body (required for write). from_agent: Name of the agent leaving the note (default "default"). note_id: Note id (required for resolve).

Returns: JSON result.

List configured providers and their safe, public configuration.

API keys are never returned; only the name of the environment variable that supplies a key (if any) is shown.

Returns: JSON: {"ok": true, "providers": [...]}

Create a provider configuration.

Secrets are NOT stored in the config: pass the NAME of an environment variable (e.g. 'MISTRAL_API_KEY') as api_key_env and the value will be resolved at request time from the server's environment.

Args: name: Unique provider id (lowercase, '-' or '_' allowed). type: Provider type (stub, openai_compatible, ollama). endpoint: Base URL for the provider API. api_key_env: Environment variable name holding the API key. options: JSON object with provider-specific options (e.g. model, timeout).

Returns: JSON result.

Update an existing provider's endpoint, api_key_env, or options.

Args: name: Existing provider id. endpoint: New base URL (empty leaves unchanged). api_key_env: New env-var name (empty leaves unchanged). options: JSON object merged into existing options.

Returns: JSON result.

Delete a provider configuration.

Args: name: Provider id to delete.

Returns: JSON result.

List configured assistants and their relevant configuration.

Args: include_disabled: Also include disabled assistants (default False).

Returns: JSON: {"ok": true, "assistants": [...]}

Return the complete configuration for one assistant.

Args: assistant_id: Assistant id.

Returns: JSON result.

Create a new assistant profile.

The provider and model are independent and can be changed later without affecting the assistant's identity, name, or system prompt.

Args: name: Human-readable assistant name. provider: Provider id (must already exist via create_provider). model: Model name for the assistant (provider-specific). assistant_id: Optional explicit id (defaults to a slug of name). description: Short description of the assistant's role. system_prompt: System prompt defining the assistant's behavior. temperature: Sampling temperature 0.0-2.0 (optional). max_tokens: Maximum tokens in the response (optional). capabilities: JSON list of capabilities, e.g. ['swift', 'ios']. permissions: JSON list of permissions, e.g. ['read_files']. metadata: JSON object of arbitrary metadata.

Returns: JSON result.

Modify an existing assistant.

Provide only the fields to change; empty strings leave text fields unchanged. Use a special sentinel to clear optional values: temperature/max_tokens: pass 0 or -1 to reset to null.

Args: assistant_id: Assistant id to update. name: New name. description: New description. provider: New provider id. model: New model name. system_prompt: New system prompt. temperature: New temperature (0.0-2.0); -1 clears. max_tokens: New max tokens; 0 clears. capabilities: JSON list replacing current capabilities. permissions: JSON list replacing current permissions. metadata: JSON object replacing current metadata. enabled: True/False to enable or disable.

Returns: JSON result.

Delete an assistant profile.

Args: assistant_id: Assistant id to delete.

Returns: JSON result.

Enable an assistant so it can receive delegated tasks.

Args: assistant_id: Assistant id.

Returns: JSON result.

Disable an assistant; it will no longer accept delegated tasks.

Args: assistant_id: Assistant id.

Returns: JSON result.

List all capabilities available across enabled assistants.

Lets a lead agent discover which capability terms are in use so it can pick an appropriate assistant.

Returns: JSON: {"ok": true, "capabilities": [...]}

Find assistants whose capabilities match the given requirements.

Capability-based discovery so a lead agent does not need to know every assistant's id.

Args: capabilities: JSON list of required capability terms, e.g. ['swift', 'ios']. any_of: Match any capability instead of all (default all). include_disabled: Include disabled assistants in results.

Returns: JSON result.

Delegate a task to a configured assistant and return a structured task id.

The task runs asynchronously; poll get_task() for status. Task metadata includes task_id, assistant_id, status, timestamps, task, context, result and error.

Args: assistant_id: Assistant id to delegate to. task: The task/instruction for the assistant. context: JSON object of additional context for the assistant. timeout: Per-task timeout in seconds (defaults to the global default). depth: Current delegation depth (advanced; leave 0 for top-level tasks). mode: Delegation mode (delegate, parallel, review, debate, pipeline).

Returns: JSON: {"ok": true, "task": {...}} with task_id and status "queued".

Return the current state/result of a delegated task.

Args: task_id: Task id from delegate_task.

Returns: JSON result.

List recent or active delegated tasks.

Args: status: Filter by status (queued, running, completed, failed, cancelled). assistant_id: Filter by assistant id. limit: Maximum number of tasks to return (default 50).

Returns: JSON result.

Cancel a queued or running task when possible.

Args: task_id: Task id to cancel.

Returns: JSON result.

Delegate the same task to multiple assistants in parallel.

Args: assistant_ids: JSON list of assistant ids. task: The task/instruction for the assistants. context: JSON object of additional context. timeout: Per-task timeout in seconds. depth: Current delegation depth.

Returns: JSON: {"ok": true, "tasks": [...]}

Delegate a task to a worker, then have a reviewer critique the work.

Args: worker_id: Assistant id for the worker. reviewer_id: Assistant id for the reviewer. task: The task/instruction. context: JSON object of additional context. timeout: Per-task timeout in seconds. depth: Current delegation depth.

Returns: JSON: {"ok": true, "worker_task": {...}, "reviewer_task": {...}}

Delegate a task to multiple assistants for competing analyses.

Args: assistant_ids: JSON list of assistant ids. task: The task/instruction. context: JSON object of additional context. timeout: Per-task timeout in seconds. depth: Current delegation depth.

Returns: JSON: {"ok": true, "tasks": [...]}

Chain assistants where output from one becomes input to the next.

Args: assistant_ids: JSON list of assistant ids in pipeline order. task: The initial task/instruction. context: JSON object of additional context. timeout: Per-task timeout in seconds. depth: Current delegation depth.

Returns: JSON: {"ok": true, "tasks": [...]}

Configure task manager safety limits.

Args: max_concurrent: Maximum concurrent tasks. default_timeout: Default timeout in seconds. max_depth: Maximum delegation depth. max_spawned_agents: Maximum spawned agents. require_command_approval: Require approval for command execution. require_file_write_approval: Require approval for file writes. require_destructive_approval: Require approval for destructive operations.

Returns: JSON: {"ok": true, "config": {...}}

Request approval for a task (for human-in-the-loop workflows).

Args: task_id: Task id to request approval for. approval_type: Type of approval (command, file_write, destructive, manual).

Returns: JSON: {"ok": true, "approval": {...}}

Approve or reject a pending approval request.

Args: approval_id: Approval id to resolve. approved: True to approve, False to reject.

Returns: JSON: {"ok": true, "approval": {...}}

List all pending approval requests.

Returns: JSON: {"ok": true, "approvals": [...]}

Write a categorized memory entry.

Memory is intentionally structured and explicit — BlackBox does not automatically store everything.

Args: category: Memory category (project_facts, architectural_decisions, discoveries, bugs, failed_approaches, recommendations, agent_observations, user_instructions). value: JSON-serializable value to store. project: Optional project scope (e.g. absolute path). key: Optional human-readable key. tags: JSON list of tags for search/filtering. source_agent: Optional agent id that wrote this entry. metadata: JSON object of additional metadata.

Returns: JSON: {"ok": true, "entry": {...}}

Retrieve a memory entry by id.

Args: entry_id: Memory entry id.

Returns: JSON: {"ok": true, "entry": {...}} or not found.

Search memory by project, category, tags, or free text.

Args: project: Optional project scope. category: Optional category filter. tags: JSON list of required tags (all must match). query: Free text search across key/value/tags/metadata. limit: Maximum results (default 50).

Returns: JSON: {"ok": true, "entries": [...]}

Delete a memory entry by id.

Args: entry_id: Memory entry id.

Returns: JSON result.

List all memory categories in use (optionally scoped to a project).

Args: project: Optional project filter.

Returns: JSON: {"ok": true, "categories": [...]}

Clean up old memory entries based on retention policy.

Args: max_age_days: Maximum age in days (default 90). max_entries: Maximum number of entries to keep (default 10000).

Returns: JSON: {"ok": true, "cleanup": {...}}

Scan a local project directory and record its structure for later reuse.

Args: path: Absolute or relative path to the project directory. depth: Maximum directory nesting included in the tree (default 4). save: Persist the summary to local storage (default True).

Returns: A JSON summary of the project.

Return a concise overview of BlackBox status.

Includes:

• number of configured assistants

• available providers

• available models

• memory statistics

• active delegations

• delegation depth

• available capabilities

Does NOT expose secrets.

Returns: JSON: {"ok": true, "status": {...}}

Explain BlackBox capabilities and how an agent should use them.

Returns a concise reference for MCP clients (including Zed) so they can understand what BlackBox can do without external documentation.

Returns: JSON: {"ok": true, "help": {...}}