convez.ai
MCP Server
jtmuller5

brainfables-skill

jtmuller5/brainfables-skill

Ver no GitHub
InicialPluginScore · de 0 a 100

Live project dashboards for coding agents: a skill + CLAUDE.md prompt that keeps your BrainFables dashboard current over MCP — last task, copy items, todos, mermaid diagram, and a fable-format timeline.

Instalação

$npx convez-ai jtmuller5/brainfables-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

brainfables

An agent skill that gives you a live dashboard of what your coding agent is doing. You keep your project's BrainFables dashboard open in a tab; your agent keeps it current over MCP as it works:

  • Last task — what the agent is working on right now
  • Copy & paste — commands, env var names, and URLs it needs you to copy
  • Todos — manual actions only you can do (set a secret, grant a permission), checked off on the page
  • Architecture — a mermaid diagram of the project, updated as the structure changes
  • Timeline — an append-only entry for every completed task, written in the fable format: a self-contained interactive explainer of the problem, the journey, and the fix

The dashboard polls every few seconds, so updates appear while the agent works — it's how your agent communicates with you when it needs something.

Fables — standalone publishable explainers — still exist on BrainFables as a personal collection, but this skill is about the dashboard loop.

Setup

Two things: the brainfables MCP server (how the agent reads and writes the dashboard) and the instruction to keep it current (this skill, or a CLAUDE.md prompt).

1. Add the MCP server

The server lives at https://brainfables.com/api/mcp (stateless Streamable-HTTP). Authenticated tools need a Bearer API key — create one on your profile page at brainfables.com after signing up, then create a project for your codebase on the dashboard.

claude mcp add brainfables --transport http https://brainfables.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

The get_fable_format and check_fable tools are public (no key). The key is needed for everything that touches your dashboards.

2. Tell your agent to keep the dashboard current

Option A — install as a skill (any agent supporting the Agent Skills format):

npx skills add jtmuller5/brainfables-skill

Option B — paste the prompt into your CLAUDE.md so it happens automatically (see below).

The CLAUDE.md prompt

Drop this into your project (or global) CLAUDE.md:

## Keeping the dashboard current (BrainFables)

Keep the BrainFables dashboard for this repo current via the `brainfables` MCP server:

- **When starting work**: call `set_last_task` with a one-line description of the task.
- **Timeline entry when done**: after each substantive request (a feature implemented, an
  issue debugged — not typo fixes), record one entry: `list_projects` (then
  `create_project` once if absent) → `get_fable_format` → draft a fable-format entry →
  `check_fable` until it returns ok → `add_timeline_entry` with the projectId and the
  files touched. Title it by the problem, not the diff. One entry per request.
- **When I must act manually**: `add_todo` for action items; `add_copy_item` for values
  I must copy (commands, env var names, SQL snippets). Never put secret values in any
  dashboard section.
- **Diagram**: call `set_diagram` with updated mermaid source if the architecture changed.

The tools

ToolWhat it does
get_fable_formatauthoring guide for the fable format used by timeline entries (no key)
check_fablecompile-check a timeline entry draft without saving (no key)
list_projects / create_projectfind or create the project for a codebase
get_dashboardfull dashboard state — call at session start to see open todos and where work left off
set_last_taskupdate what the agent is working on right now
set_diagramreplace the mermaid architecture diagram
add_copy_item / remove_copy_itemsurface things the owner should copy
add_todo / complete_todofile and resolve manual actions for the owner
add_timeline_entry / list_timelineappend and read the per-task history
  • Timeline entries are full fable documents (frontmatter + body) and go through the same compiler and rate limits as the web editor — content is data, not code.
  • Never put secrets anywhere on the dashboard — copy items carry commands and env var names, not values.
  • Dashboards are private to the owner. Publishing fables to the community feed remains a separate, human act on the web.

License

MIT © Joe Muller

Ver o original no GitHub

Bom para

Relacionados