Semaphor Agent Plugin
semaphor-analytics/agent-plugin
Construa data apps React conectados a dados governados com IA
Ver no GitHubPlugin que conecta Claude Code ou Codex a projetos Semaphor para construir data apps React governados. O agente pode inspecionar dados, responder perguntas de negócio, gerar código React e publicar apps diretamente no Semaphor com validação integrada.
Instalação
npx convez-ai semaphor-analytics/agent-plugin1 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
Casos de uso
- Gerar dashboards e aplicações de dados com Claude Code
- Inspecionar e explorar dados governados via agente IA
- Automatizar criação de visualizações e KPIs em React
- Publicar data apps validados direto do ambiente de desenvolvimento
Veredito

Plugin maduro e bem-documentado que integra análise de dados com geração de código. Excelente para times que já usam Semaphor e querem acelerar desenvolvimento de data apps com assistência de IA, mas requer setup inicial com tokens de projeto.
README
A tradução para o português deste README ainda está na fila.
Semaphor Agent Plugin
Build data apps and answer business questions, grounded in your data.
The Semaphor Agent Plugin connects Codex or Claude Code to your Semaphor project. Your agent can inspect governed data, answer business questions, plan KPIs and charts, generate React data-app code, validate the result, and publish the finished app back to Semaphor.
Quick Start
1. Install
Add the Semaphor marketplace from GitHub, then install the plugin.
Codex:
codex plugin marketplace add semaphor-analytics/agent-plugin
codex plugin add semaphor@semaphor-analytics
Claude Code:
claude plugin marketplace add semaphor-analytics/agent-plugin
claude plugin install semaphor@semaphor-analytics
2. Open Or Create A React App
If you already have a React app, use that app. If you are starting fresh, use the Semaphor Data App Starter:
git clone https://github.com/semaphor-analytics/semaphor-data-app-starter.git my-data-app
cd my-data-app
npm install
The starter is a simple Vite + shadcn app with the basics in place so the agent can focus on your data app instead of initial project setup.
3. Connect To Semaphor
If you do not have a project token configured, log in with Semaphor.
From Codex:
codex mcp login semaphor
From Claude Code, run the /mcp slash command in your session and complete the
OAuth flow for the semaphor server.
After login, ask the agent to list your projects and choose the project for
this app. If the app needs to run locally, the agent can mint a scoped
development runtime token for that project and write
VITE_SEMAPHOR_PROJECT_TOKEN to the app's ignored .env.local. The OAuth
token itself is never written into the app.
If you already know the project and want a deterministic scoped setup, create or update your app's ignored local env file:
VITE_SEMAPHOR_PROJECT_TOKEN="<project-token-from-semaphor-project-page>"
Get project tokens from your Semaphor project page:
https://semaphor.cloud/project
Do not commit real tokens.
4. Open Your App
Start your coding agent from the app directory (codex or claude) and try:
Inspect my Semaphor project and propose a data app plan.
Semaphor should inspect your project data, propose a plan, and then help build the app once you approve the direction.
What You Need
- A Vite React app. For a new app, start with semaphor-data-app-starter. Existing Vite React apps and monorepos are fine too.
- Semaphor login, or a Semaphor project token for deterministic scoped development.
- Codex or Claude Code.
react-semaphorin your app. The agent can add it if it is missing.
Codex Commands
Install
codex plugin marketplace add semaphor-analytics/agent-plugin
codex plugin add semaphor@semaphor-analytics
Verify
codex plugin marketplace list
codex plugin list --marketplace semaphor-analytics
After installation, Semaphor MCP tools should be available to Codex as first-class callable tools. The plugin exposes:
semaphor: hosted OAuth MCP for login and project discovery.semaphor-project: project-token MCP bridge for scoped/local development.
Upgrade
codex plugin marketplace upgrade semaphor-analytics
If Codex still shows an older plugin after upgrading the marketplace, remove and reinstall the plugin:
codex plugin remove semaphor@semaphor-analytics
codex plugin add semaphor@semaphor-analytics
Remove
Remove only the installed plugin:
codex plugin remove semaphor@semaphor-analytics
Remove the marketplace source as well:
codex plugin marketplace remove semaphor-analytics
plugin remove removes the installed plugin. marketplace remove removes the
marketplace source.
Debug MCP Tool Access
Most users should not need this. Use it only when debugging from a local checkout of this repository and a host does not expose the Semaphor MCP tools as first-class callable tools:
npm run call:mcp -- --list-tools --dir /path/to/react-app
npm run call:mcp -- semaphor_get_access_context --dir /path/to/react-app
Claude Code Commands
Install
claude plugin marketplace add semaphor-analytics/agent-plugin
claude plugin install semaphor@semaphor-analytics
Or, from inside a Claude Code session:
/plugin marketplace add semaphor-analytics/agent-plugin
/plugin install semaphor@semaphor-analytics
Restart Claude Code (or run /reload-plugins) so the new plugin and its MCP
servers are picked up.
Verify
claude plugin marketplace list
claude plugin list
After installation, Semaphor MCP tools should be available to Claude Code as first-class callable tools. The plugin exposes:
semaphor: hosted OAuth MCP for login and project discovery.semaphor-project: project-token MCP bridge for scoped/local development.
If a tool call asks for OAuth on first use, complete the login through the
/mcp slash command in your Claude Code session, then re-run the request.
Upgrade
claude plugin marketplace update semaphor-analytics
If Claude Code still shows an older plugin after updating the marketplace, remove and reinstall the plugin:
claude plugin uninstall semaphor@semaphor-analytics
claude plugin install semaphor@semaphor-analytics
Remove
Remove only the installed plugin:
claude plugin uninstall semaphor@semaphor-analytics
Remove the marketplace source as well:
claude plugin marketplace remove semaphor-analytics
plugin uninstall removes the installed plugin. marketplace remove removes
the marketplace source.
Debug MCP Tool Access
Most users should not need this. Use it only when debugging from a local checkout of this repository and a host does not expose the Semaphor MCP tools as first-class callable tools:
npm run call:mcp -- --list-tools --dir /path/to/react-app
npm run call:mcp -- semaphor_get_access_context --dir /path/to/react-app
Connect To Semaphor
The lowest-friction first run is Semaphor login.
From Codex:
codex mcp login semaphor
From Claude Code, run the /mcp slash command in your session and complete the
OAuth flow for the semaphor server.
Then ask the agent:
What Semaphor projects can I use?
For deterministic scoped app development, put a project token in .env.local:
VITE_SEMAPHOR_PROJECT_TOKEN="<project-token-from-semaphor-project-page>"
The plugin helper scripts can also read:
SEMAPHOR_PROJECT_TOKEN="<project-token-from-semaphor-project-page>"
Hosted Semaphor does not require a separate server URL. Self-hosted or custom Semaphor deployments may set:
SEMAPHOR_SERVER_URL="https://your-semaphor-host"
When SEMAPHOR_SERVER_URL is absent, the plugin uses the Semaphor host encoded
in the project token and falls back to https://semaphor.cloud.
For production apps, provide runtime tokens through your backend, Semaphor embed/token flow, or Semaphor hosted Data App runtime.
When using OAuth for local development, ask the agent to mint or refresh the local runtime token instead of manually copying one:
Mint a local runtime token for this project.
The agent should use semaphor_get_data_app_runtime_token, write the returned
project token only to ignored local env, and avoid printing it.
Good First Prompts
Create a data app from my project.
Add a revenue chart with period-over-period change.
What's driving the trend in my top KPI?
Publish this app to Semaphor.
Common Workflows
Answer A Business Question
Why did revenue change last month?
Plan A Data App
Plan an operations data app from my Semaphor project.
Add A View
Add a revenue trend and segment table to this page.
Add Filters
Add a region filter and make the KPI, trend, and table respond to it.
Build Matrix Or Pivot Tables
Show revenue by region and segment with row totals and a grand total.
Add Governed Calculations
Add gross margin as a derived metric.
Use SQL When Needed
Use SQL to show the latest raw inventory movement rows, then add a bounded table.
Save Or Publish
Save this as a Semaphor Data App named "Operations App".
Publish the latest revision to Semaphor.
What The Agent Should Do
For broad app-building requests, the agent should:
- Inspect your Semaphor project metadata.
- Plan the app before writing code.
- Explain which views are backed by governed queries and which gaps need model improvements.
- Generate React code using
react-semaphor/data-app-sdk. - Validate loading, empty, error, and data states.
- Save or publish the app when you approve it.
The agent should not hardcode sample data when a view should execute governed Semaphor analytics.
Generated Code Pattern
The plugin generates standard React code using the public Semaphor Data App SDK:
import {
SemaphorDataAppProvider,
SemaphorDevtools,
semaphor,
useSemaphorQuery,
} from "react-semaphor/data-app-sdk";
Generated local/dev apps should mount the SDK DevTools root once near the provider so developers and agents can inspect query traces:
const enableDevtools =
import.meta.env.DEV ||
(typeof window !== "undefined" && window.location.hostname === "localhost");
<SemaphorDataAppProvider
token={runtimeToken}
debug={enableDevtools ? { exposeWindowBridge: true } : false}
>
<App />
<SemaphorDevtools
initialIsOpen={false}
buttonPosition="bottom-right"
panelPosition="right"
/>
</SemaphorDataAppProvider>
The window bridge is for local/dev agent inspection only. Do not enable it for production embeds or normal end-user runtime code.
Typical query pattern:
const revenueQuery = semaphor.metric({
id: "total-revenue",
source,
measures: [revenue],
primaryMeasure: revenue,
});
function RevenueKpi() {
const result = useSemaphorQuery(revenueQuery);
if (result.isLoading) return <span>Loading...</span>;
if (result.error) return <span>{result.error.message}</span>;
return <strong>{formatNumber(result.value)}</strong>;
}
The plugin supports:
- metrics
- records and tables
- filters and controls
- driver and period-change analysis
- matrix and pivot tables
- derived fields
- SQL-backed views when governed builders cannot express the question
- save and publish to Semaphor
Validate Your App
Ask the agent to validate the app before you review or publish it:
Validate this Semaphor data app and run the app's normal typecheck/build.
The agent should use your app's existing package manager and scripts, then run Semaphor-specific checks for common SDK and publish issues.
Publish To Semaphor
Ask the agent to save or publish when the app is ready:
Save this as a Semaphor Data App named "Operations App".
Publish the latest revision to Semaphor.
The first save or publish creates a Semaphor-hosted Data App and writes its
identity to semaphor.data-app.json. Later saves and publishes update the
same app.
Repository Layout
This GitHub repo is the marketplace root for both Codex and Claude Code:
agent-plugin/
.agents/plugins/marketplace.json # Codex marketplace catalog
.claude-plugin/marketplace.json # Claude Code marketplace catalog
plugins/semaphor/ # Shared installable plugin package
Codex and Claude Code use different marketplace file locations, but both
marketplaces point to the same plugins/semaphor package.