Building a Local Twin (Density CLI)

This post is about the Density CLI and why we are building it.

Density has always measured the physical world. Our sensors count how people use buildings, floors, rooms, desks, and shared spaces. Atlas turns that data into charts and workflows for workplace teams.

But AI changes what customers expect from software. They no longer only want dashboards. They want to ask better questions of their workplace data and get answers they can inspect, trust, and reuse.

• Which rooms are consistently underused?
• Which floors feel busy on Tuesdays but empty on Fridays?
• Where are we paying for space that people do not use?
• What changed after we moved this team?
• Can you make me the chart I would have built myself, if I had three uninterrupted hours?

To answer those questions well, an AI system needs more than a generic API call. It needs local, queryable, inspectable data. It needs to know the shape of the customer’s workplace and the history of how that workplace has been used.

That is what the Density CLI is for.

A local analytical cache

The CLI downloads a customer’s Density data into local DuckDB and Parquet files. It stores spaces, occupancy, utilization, entry counts, events, and other records in a form that an engineer or AI agent can query directly.

This matters because local data changes the workflow. Instead of asking an API the same narrow question again and again, an agent can build up a working set of truth. It can inspect the schema. It can run SQL. It can generate charts. It can compare rooms, floors, buildings, labels, and time periods. It can produce artifacts that are reproducible instead of screenshots that disappear into Slack.

Chart faithfulness

The CLI is also becoming the baseline for chart faithfulness.

Atlas already has years of chart logic. Some of that logic is simple. Some of it is subtle. Meeting-room utilization, operating hours, uptime filtering, occupancy rollups, weekday comparisons, and space hierarchy all have details that matter.

If an AI agent says, “Here is the busiest room,” we need to know whether it means the same thing Atlas would mean.

So we are teaching the CLI to recreate Atlas-style chart outputs from local data.

That work is practical and unglamorous in the best way. It means mapping exact API calls to local DuckDB queries. It means knowing the interval, time period, space scope, rollup behavior, and filtering rules behind each chart. It means making the local answer boringly consistent with the product answer.

Boring consistency is the foundation of useful AI.

Local-first, not isolated

One of the most important design choices is that the CLI is local-first.

Customers should be able to keep a durable analytical cache on their own machine. Density employees helping customers should be able to sync data, inspect it, create charts, and explain exactly what happened. The system should not depend on a hidden notebook or a one-off script that only one person understands.

Local-first does not mean isolated from our product. The CLI still authenticates against Density. It still respects organization access. It still syncs customer-owned data from Density APIs. But once the data is local, it becomes easier to reason about, easier to test, and easier for AI agents to use safely.

What local data teaches us

This has already surfaced important engineering lessons.

For example, Density employees often work across multiple customer organizations. That means one local database may contain multiple orgs. The rows are keyed by organization, but sync state must be keyed by organization too. Otherwise one customer’s sync watermark could accidentally make another customer’s data look complete.

That is the kind of bug a dashboard may hide for a long time. A local analytical system forces us to make the boundary explicit.

We have also found that some existing product APIs are not the right long-term shape for local AI workflows. A chart API may accept local wall-clock time because that is natural for a product screen. But a CLI that syncs historical data wants exact instants. It wants “from this moment to that moment,” not “9am in whatever timezone this space happens to use.”

The better architecture

This is why we are excited about the new Data Access API work.

The better architecture is: Data Access API → Parquet → DuckDB → Atlas-shaped local query → chart or answer.

That puts the hard data interpretation in the right place. The server can handle timezone, counting mode, space eligibility, and historical export semantics. The CLI can focus on local storage, query, visualization, and AI workflows.

The end goal

A customer should be able to ask a question about their workplace and get an answer that is fast, inspectable, and faithful to the underlying data.

A Density teammate should be able to sit with a customer, pull the right local baseline, and build the chart or analysis they need in minutes.

An AI agent should be able to work against the same durable facts a human engineer would use.

That is the point of the Density CLI.

It is not just a developer tool. It is the local workbench for understanding the physical world.