Data
Plugin
datastoria
The AI-native ClickHouse console for your cluster diagnostics, query generation, evidence-based optimization, intelligent visualization.
Plugin Signal72/100Solid
maintained90
capable43
documented100
adopted53
Install
$ npx -y skills add FrankChen021/datastoria --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
325
Stars
18
Forks
Active
Maintenance
TypeScript
Language
19d ago
Last commit
9mo ago
Created
Repo: FrankChen021/datastoria
What's inside
Skills
7/clickhouse-system-queriesQuery ClickHouse system tables to inspect query logs, monitor cluster health, check replication status, and analyze slow queries. Use when the user mentions "system tables", "query_log", "ClickHouse monitoring", "cluster status", "slow queries", or asks to diagnose ClickHouse/diagnose-clickhouse-clustersDiagnose ClickHouse cluster health and provide concrete remediation./diagnose-clickhouse-errorsDiagnose ClickHouse runtime query failures when the user wants database-level cause and fix guidance from an error or numeric error code, not source-code root cause analysis./optimize-clickhouse-sqlOptimize slow queries, analyze SQL performance, and collect evidence for expensive workloads./source-code-inspectionInvestigate application or repository source code with search_file and read_file to explain behavior, trace root causes of runtime or query errors, and answer with precise file citations./sql-expertExpert system for generating, validating, and optimizing ClickHouse SQL. Use this when the user needs data, queries, or analysis.
README
1DataStoria
The AI-native ClickHouse console for your cluster diagnostics, query generation, evidence-based optimization, intelligent visualization.
Demo
📖 More demo/screenshots at docs.datastoria.app
🚀 Key Features
🤖 AI Features
- Natural Language Data Exploration — Describe your data needs in plain English and receive optimized ClickHouse queries instantly.
- Smart Query Optimization — AI inspects schema, validates SQL, collects evidence, and recommends concrete ClickHouse performance improvements.
- Intelligent Visualization — Ask for a chart in plain language and DataStoria generates both the SQL and the visualization spec for time series, bar, pie, and table views.
- Agent SKILLs Supported — Skill-based agent architecture that saves tokens across multi-turn conversations; apply the Official ClickHouse Agent Skills to your ClickHouse
- Multiple Model Providers — Use OpenAI, Anthropic Claude, Google Gemini, GitHub Copilot, OpenRouter, Groq, Cerebras, Nebius and more.
- GitHub Copilot Integration — Sign in with GitHub device flow and use your existing Copilot subscription for chat, query assistance, and other AI-powered workflows.
⚡ Powerful Query Experience
- Advanced SQL Editor — Enjoy syntax highlighting, auto-completion, and query formatting for a seamless coding experience.
- Smart Error Diagnostics — Pinpoint syntax errors instantly with precise line and column highlighting, and get AI-powered fix suggestions with one click.
- System Log Inspector — Dive deep into query execution with timeline views, topology graphs, and performance analysis as well as Materialized Views, ZooKeeper states.
- One-Click Explain — Instantly understand query execution plans with visual AST and pipeline views.
- Dependency Graph — Visualize table relationships and trace data flows through Materialized Views, Distributed tables, and external systems.
📊 Cluster Monitoring & Management
- Multi-Cluster Support — Manage multiple ClickHouse clusters effortlessly from a single interface.
- Multi-Node Dashboard — Monitor all nodes with real-time metrics, merge operations, and replication status.
- Cluster wide Dashboards — Access pre-configured panels for query performance, ZooKeeper status, and more.
- Schema Explorer — Navigate databases, tables, and columns with an intuitive tree view.
🔒 Privacy & Security
- 100% Local Execution — All SQL queries run directly from your browser to your ClickHouse server, ensuring complete privacy.
- No Data Collection — Your credentials and query results never leave your machine.
- Bring Your Own API Key — Use your own LLM API keys for AI features, keeping your data under your control.
- Browser-Side Visualization Rendering — For AI-generated visualizations, the model produces SQL and chart specs while your browser fetches and renders the data locally.
🌐 Experience the app
Visiting dataStoria.app to experience all features without any installation.
🛠️ Build from Source
Prerequisites:
Follow these steps to build and run locally:
# Clone the repository
git clone --recurse-submodules https://github.com/FrankChen021/datastoria.git
cd datastoria
# Install dependencies
npm install --force
# Start the development server
npm run dev
Open http://localhost:3000 in your browser and connect to your ClickHouse instance.
🐳 Running with Docker
The easiest way to run DataStoria is using the pre-built Docker image:
docker run -d -p 3000:3000 frankchen021/datastoria:latest
Then open http://localhost:3000 in your browser.
The Docker image supports both linux/amd64 and linux/arm64 platforms, so it runs natively on Intel/AMD machines as well as Apple Silicon Macs and ARM-based servers.
📖 Documentation
User Manual
Development
- Docker Deployment — Build and run with Docker
- LLM Provider API Key Configuration — Configure API keys for your LLM provider
- Authentication Guide — OAuth setup for Google, GitHub, and Microsoft
🧰 Tech Stack
- Framework: Next.js 16 with React 19
- AI Integration: Vercel AI SDK with support for OpenAI, Anthropic, Google, Groq, and more
- Authentication: NextAuth.js
📜 License
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
DataStoria is an AI-native ClickHouse console for modern query, visualization, and diagnostics workflows.
File tree
758FrankChen021/datastoriaView on GitHub
.codex/
.gitignore
config.toml
hooks/
hooks.json
after_change.sh
.dockerignore
.env.example
.eslintrc.json
.github/
workflows/
ci.yml
cleanup-deployments.yml
release.yml
.gitignore
.gitmodules
.npmrc
.prettierignore
.prettierrc
AGENTS.md
components.json
docker/
Dockerfile
README.md
docs/
.vitepress/
components/
FeatureCarousel.vue
Mermaid.vue
Video.vue
config.mts
theme/
custom.css
index.ts
dev/
authentication.md
llm-provider-api-key.md
plan/
query-error-auto-explain.md
index.md
manual/
01-getting-started/
first-connection.md
img/
create-new-connection.png
first-query.png
main-page.png
test-connection-ok.png
welcome.png
installation.md
introduction.md
02-ai-features/
ai-model-configuration.md
ask-ai-for-help.md
cluster-health-advisor.md
github-copilot.md
img/
ask-ai-for-help-example-1.jpg
ask-ai-settings-auto-explain.webp
ask-ai-settings-blacklist-picker.webp
auto-explanation.webp
chat-example-1.png
chat-example-2.jpg
chat-example-3-table-schema.jpg
chat-example-3.jpg
chat-example-4.jpg
chat-example-slowest-query.jpg
chat-panel.png
command-explain-error-code.png
copilot-1.jpg
copilot-2.jpg
copilot-3.jpg
copilot-4.jpg
copilot-5.jpg
copilot-7.jpg
model-configuration-search.png
model-configuration.png
select-model.png
sql-optimization-example-1.jpg
sql-optimization-example-2.jpg
visualization-example-2.jpg
visualization-example-3.jpg
visualization-example-4.jpg
visualization-example.jpg
intelligent-visualization.md
natural-language-sql.md
query-optimization.md
skills.md
slash-commands.md
03-query-experience/
error-diagnostics.md
img/
error-diagnostics-1.jpg
explain_actions.jpg
explain_ast.jpg
explain-ast-2.jpg
explain-estimate.jpg
explain-index.jpg
explain-pipeline.jpg
query-log-inspector-table-view-2.jpg
query-log-inspector-table-view.jpg
query-log-inspector-timeline-detail.jpg
query-log-inspector-timeline-hover.jpg
query-log-inspector-timeline.jpg
query-log-inspector-topo.jpg
query-log-inspector.jpg
snippet-ai.jpg
snippet.jpg
sql-editor-1.jpg
sql-editor-suggestion-1.jpg
sql-editor-suggestion-2.jpg
sql-editor-suggestion-3.jpg
sql-editor-suggestion-4.jpg
sql-editor-suggestion-5.jpg
sql-editor-suggestion-6.jpg
query-execution.md
query-explain.md
query-log-inspector.md
sql-editor.md
sql-snippets.md
04-cluster-management/
database-view.md
dependency-view.md
img/
dashboard-cluster-status.jpg
dashboard-node-status.jpg
dashboards-open-cluster-status.jpg
database-tab.jpg
dependency-view-database.jpg
schema-explorer-search-1.jpg
schema-explorer-search-2.jpg
schema-explorer-search-3.jpg
system-ddl-distributed-queue.webm
system-opentelemetry-span-log-inspector.webm
system-opentelemetry-span-log.jpg
system-part-log-introspection.webm
system-processes.jpg
system-query-log-1.jpg
system-query-log.webm
system-query-views-log.webm
system-table-introspection-1.jpg
system-zookeeper.jpg
table-tab-dependency.jpg
table-tab-overview.jpg
table-tab-part-log.jpg
table-tab-partition.jpg
table-tab-query-log.jpg
opentelemetry-span-log.md
schema-explorer.md
system-ddl-distributed-queue.md
system-log-introspection.md
system-part-log.md
system-processes.md
system-query-log.md
system-query-views-log.md
system-zookeeper.md
table-view.md
05-monitoring-dashboards/
cluster-dashboard.md
img/
dashboard-cluster-status.jpg
dashboard-node-status.jpg
dashboards-open-cluster-status.jpg
node-dashboard.md
06-security-privacy/
privacy-features.md
index.md
public/
_headers
logo.png
README.md
robots.txt
site.webmanifest
eslint.config.mjs
external/
instrumentation.ts
LICENSE
next.config.ts
package-lock.json
package.json
postcss.config.mjs
public/
logo.png
provider-logos/
anthropic.svg
cerebras.svg
github-copilot.svg
google.svg
groq.svg
nebius.svg
openai.svg
openrouter.svg
robots.txt
site.webmanifest
README.md
resources/
database/
mysql.sql
postgres.sql
sqlite.sql
rca/
high-part-count.yaml
skills/
clickhouse-system-queries/
references/
system-query-log.md
SKILL.md
diagnose-clickhouse-clusters/
SKILL.md
diagnose-clickhouse-errors/
references/
115.md
342.md
42.md
47.md
60.md
SKILL.md
optimize-clickhouse-sql/
SKILL.md
source-code-inspection/
SKILL.md
sql-expert/
SKILL.md
visualization/
SKILL.md
scripts/
copy-docs-manual-img.mjs
copy-resources.mjs
download-release-notes.mjs
generate-release-notes.mjs
sync-skills.mjs
src/
app/
ai/
feedback/
page.tsx
api/
ai/
agent/
route.ts
chat/
feedback/
auto-explain/
route.ts
report/
route.ts
route.ts
sessions/
[sessionId]/
messages/
route.ts
route.ts
route.ts
v2/
route.ts
codex/
auth/
refresh/
route.ts
token/
route.ts
commands/
route.ts
github/
auth/
device/
code/
route.ts
token/
route.ts
refresh/
route.ts
models/
route.ts
models/
available/
route.test.ts
route.ts
rca/
templates/
route.ts
sessions/
[sessionId]/
share/
route.ts
skills/
[id]/
resource/
route.ts
route.ts
actions/
review/
route.test.ts
route.ts
route.ts
auth/
[...nextauth]/
route.ts
connections/
templates/
route.ts
code-viewer/
page.tsx
error.tsx
layout.tsx
login/
agreement-dialog.tsx
login-form.tsx
page.tsx
page.tsx
session/
[sessionId]/
page.tsx
sitemap.ts
assets/
react.svg
auth-private.ts
auth.ts
components/
ai/
feedback/
auto-explain-feedback-report.tsx
app-logo.tsx
app-shell.tsx
app-sidebar.test.tsx
app-sidebar.tsx
app-storage-provider.tsx
chat/
agent-command-browser-panel.tsx
agent-command-context.tsx
chat-action-context.tsx
chat-context.test.ts
chat-context.ts
chat-factory.test.ts
chat-factory.ts
chat-ui-context.ts
input/
chat-input-commands.tsx
chat-input-suggestions.test.tsx
chat-input-suggestions.tsx
chat-input.images.test.tsx
chat-input.resize.test.tsx
chat-input.test.ts
chat-input.tsx
command-utils.test.ts
command-utils.ts
inline-token.test.ts
inline-token.ts
mention-utils.ts
model-selector-impl.tsx
model-selector.tsx
setting-token-utils.ts
sql-snippet-token.test.ts
sql-snippet-token.ts
mention-descriptions.tsx
message/
chat-message-list.test.tsx
chat-message-list.tsx
chat-message-parts.test.ts
chat-message-parts.ts
chat-message.tsx
chat-token-status.tsx
collapsible-part.test.tsx
collapsible-part.tsx
file-link.test.ts
file-link.ts
message-error.tsx
message-markdown-chat.tsx
message-markdown-math.ts
message-markdown-sql.tsx
message-markdown-vizlayer.test.tsx
message-markdown-vizlayer.tsx
message-markdown.test.tsx
message-markdown.tsx
message-reasoning.tsx
message-tool-ask-user-question.test.tsx
message-tool-ask-user-question.tsx
message-tool-collect-sql-optimization-evidence.tsx
message-tool-execute-sql.test.tsx
message-tool-execute-sql.tsx
message-tool-explore-schema.tsx
message-tool-general.tsx
message-tool-generate-sql.tsx
message-tool-generate-visualization.tsx
message-tool-get-tables.tsx
message-tool-plan.tsx
message-tool-read-file.tsx
message-tool-search-file.tsx
message-tool-skill.test.tsx
message-tool-skill.tsx
message-tool-validate-sql.tsx
message-user.test.tsx
message-user.tsx
remark-extensions.test.ts
remark-extensions.ts
skill-link.test.ts
skill-link.ts
tool-progress-indicator.tsx
session/
chat-session-list.tsx
... 521 moreFAQ
datastoria is a Claude Code plugin with 7 hand-picked skills for data work, indexed on Flowy. Install it with the command on its page. It includes clickhouse-system-queries, diagnose-clickhouse-clusters, diagnose-clickhouse-errors. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is datastoria?
- The AI-native ClickHouse console for your cluster diagnostics, query generation, evidence-based optimization, intelligent visualization.
- How do I install datastoria?
- Run these in Claude Code: npx -y skills add FrankChen021/datastoria --agent claude-code. Then prompt normally.
- Does datastoria auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is datastoria free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.