Graphene is a data analytics framework built for coding agents.
Ask questions and build visualizations 10x faster when agents do the work.

Graphene is an everything-as-code analytics framework for SQL-based data exploration, visualization, and reporting. It is designed with coding agents in mind as the primary user persona.

It provides two critical pieces that allow coding agents to do better data work:

1. A semantic layer, which yields more accurate queries. Graphene SQL combines the power of SQL with the governance of metrics and modeled joins.
2. A dashboard file type, which yields more consistent and polished visuals compared to raw Python or Javascript.

Design goals

• Token efficiency. Languages are designed to be brief with minimal boilerplate.
• Agent ergonomics. Graphene is controlled entirely via CLI. All documentation is inside our agent skill.
• High ceilings. Graphene SQL follows ANSI and supports over 170 functions; Graphene pages support anything that can be expressed with HTML, CSS, Javascript, and ECharts.

We believe coding agents coupled with an everything-as-code analytics stack beats traditional BI in several ways:

• Broad ecosystem of SOTA LLMs, harnesses, skills, and tools
• Leverage business-wide context from other tools or repos
• Perform end-to-end tasks across tools, where analytics is just one step
• More graceful change management and bulk refactors
• Easily promote/demote logic into or out of the semantic layer
• Version control and CI. Revert agent mistakes. Run tests on mission-critical dashboards.
• Tight, complete iteration loops. Agents can validate before running, view dashboards, and iterate locally
• Leverage continuous agents for self-healing codebases

Graphene is free to use, forever. Your business logic lives in your repo and is never locked into a contract with us.

Graphene pages support visualizations, input components for filtering and dynamic behaviors, and layout modes for monitoring-oriented dashboards vs. narrative-oriented notebooks.

Traditional semantic layers give you governance at the expense of capability. They tend to expose niche query APIs that agents aren't familiar with.

Graphene SQL's goal is to bring governance without sacrificing capability. It behaves like regular SQL—with CTEs, subqueries, window functions, set operators, and more—but also adds in the concepts of measures and modeled joins from semantic layers.

Graphene SQL is inspired by Malloy, from the creators of LookML Lloyd Tabb and Michael Toy, but implements it as good old SQL for agent familiarity.

Graphene currently supports Snowflake, BigQuery, ClickHouse, Postgres, MotherDuck, and local data (via DuckDB) as data sources. It is easy for us to add more - just ask.

Once your project is set up, simply start the dev server via npm exec graphene serve (or pnpm graphene serve, etc. based on your package manager) and then prompt your coding agent to do analytics work: answer a data question, build a dashboard, edit the model, etc.

Graphene itself is a CLI which can be installed via npm (or pnpm, yarn, etc.). The CLI can run and compile Graphene SQL queries, render pages in the browser, check syntax, print screenshots, and more.

A Graphene project can either be a standalone repo or a directory within a larger codebase (such as dbt). It is comprised of semantic models via .gsql files and pages via .md files.

Semantic models are defined like so:

table orders (
  id BIGINT
  user_id BIGINT
  amount FLOAT
  status STRING

  join one users on user_id = users.id  -- many orders per user

  is_complete: status = 'Complete'      -- dimension (scalar expression)
  revenue: sum(amount)                  -- measure (agg expression)
  aov: revenue / count(*)               -- measures can compose
)

table users (
  id BIGINT
  name VARCHAR

  join many orders on id = orders.user_id
)

Models are then queried via select, either directly via CLI or inside a Graphene markdown page like this.

```sql top_customers
select
  users.name as name,   -- Use the dot operator to traverse the modeled join relationship
  revenue               -- Invokes the measure
from orders             -- A join statement here is not needed
group by 1
order by 2 desc
limit 10
```

<BigValue data="orders" value="revenue" />
<BarChart data="top_customers" x="name" y="revenue" />

Graphene's entire documentation ships as an agent skill in the Graphene npm package. The source files are available here.