Skip to content
HedronitePublic
forked from crizant/probe

About

API client optimized for humans and agents.

Resources

Stars

10 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

439 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Facet

Facet

Native, local-first API client.
Terminal CLI and TUI on Probe, with persistent run history.

CI Facet v0.8.0 facet-lattice on crates.io Rust 1.95 License

Quick start · Agent use · Install · What you get · How it works · Status · Roadmap · Contributing

Fork of Probe


Status: In production use as daily-driver / dogfood local-first API client (CLI/TUI + facet-lattice). 0.8.1 on main (this release); 0.8.0 released (Oct 29, 2026). WebSocket/GraphQL/gRPC on the roadmap. Not a toy reference.

Facet is the terminal product: a facet CLI and Ratatui TUI on the same OpenCollection YAML as Probe. facet-lattice is the run-history library underneath — SQLite for runs, bodies, timings, and sessions beside your YAML on disk.

Coding agents should use the bundled skill and the CLI (Agent use). facet mcp still serves the same commands as MCP tools over stdio.

Collections stay YAML; Git stays the sync layer. No account or hosted control plane. The facet binary coexists with probe on PATH.

0.8.0 · OpenCollection YAML · Ratatui TUI · SQLite run history

Quick start

Library — facet-lattice on crates.io

cargo add facet-lattice
[dependencies]
facet-lattice = "0.5.9"
use lattice::WorkspaceStore;

The Cargo package is facet-lattice (not lattice — that name on crates.io is unrelated). The Rust import name is lattice.

CLI — the facet binary

The CLI is not cargo install facet. The Cargo package is facet-cli; the binary is facet.

v0.8.0 tag (primary, Rust required):

cargo install --git https://github.com/Hedronite/facet --tag v0.8.0 --locked --bin facet facet-cli

From main (secondary): cargo install --git https://github.com/Hedronite/facet --locked --bin facet facet-cli, or clone and cargo build --release -p probe-cli -p facet-cli. See docs/install.md.

Release archive: download from GitHub Releases, extract facet, add to PATH.

Verify: facet --version and facet doctor --json.

Run a request and query history

facet request run ./api/users/list-users.yml --environment development --json
facet history --json
facet history --sql "SELECT status, count(*) FROM runs GROUP BY status"
facet blob <sha256>
facet tui

More commands (facet --help for flags):

Command What it does
facet last [<path>] Newest matching run; prints its ULID (same filters as history)
facet pin <runId> --as <name> Name a run in the machine store (pin get, pin list, pin delete)
facet session start|end|list|show Group runs into a session (use with FACET_SESSION)
facet replay <runId> Re-send a recorded run from the current YAML
facet diff <idA> <idB> Compare two recorded runs, hashes first (exit 1 if different)
facet theme check <path> / facet theme list Validate a facet-tui theme file; list built-in and discovered themes
facet ncl check|export|apply|pack Check, export, apply, or pack Nickel (.ncl) configs, evaluated in-process
facet mcp Same commands as MCP tools over stdio; still shipped. Agents should prefer the skill

Full install guide (wrong-name traps, PATH, versions): docs/install.md.

Example collection for calling the TypeSafe API from facet (judge-style requests, API key stored with facet env set --secret): docs/jev-native.md and docs/examples/typesafe/.

Agent use: skills + CLI first, MCP still shipped

The default way for an agent to use this tool is the bundled skill in .agents/skills/facet/: a short SKILL.md the harness reads to decide when to use it, plus a Nushell body that calls the CLI with JSON output. The MCP server (facet mcp) is still built and shipped, and works the same as before.

Why the skill is the default:

  • Context. An MCP server adds every tool's name, description and input schema to the model's context, often on every request, whether or not the tools are used. Many harnesses can only turn a whole server on or off. A skill costs a few dozen tokens of description until it is used.
  • Determinism. The skill body is fixed code over a versioned JSON contract, so results are the same each time.
  • Small models. Local models with short context windows feel the schema cost most.

Use the MCP server when your harness defers or filters MCP tool schemas (loading them only on demand, or letting you enable single tools), or when the client has no shell.

The same files are checked in as ordinary files (not symlinks) at .claude/skills/facet/, .grok/skills/facet/, and .cursor/skills/facet/. scripts/sync-skills rewrites those copies from .agents/skills/. There is no .omp/skills/ or .codex/skills/ tree.

TUI quick reference

Key or command Action
:open <path> Mount a collection without quitting
:recent Open recently recorded collections
? Show the complete keymap and command hints

What you get

Upstream Probe Facet (this repository)
Core Engine Rust, filesystem-first Same core, cherry-pickable
Collections OpenCollection YAML Same YAML, 100% compatible
Interface GPUI Desktop + CLI (upstream) Ratatui TUI (facet tui) + agent CLI; the in-repo probe binary is CLI-only
History In-memory session facet-lattice (SQLite workspace & machine store)
Binaries probe facet (coexists with probe)
Output Human-readable & JSON Deterministic, versioned JSON for automation

Facet rebuilds the terminal and history layers; Probe owns the core domain and HTTP execution. Boundary: docs/FACET.md.

How it works

YAML holds the collection; facet-lattice holds the history.

  • .facet/lattice.db beside your collection stores run history; a machine store holds secrets, sessions, and a cross-workspace index.
  • Agent commands (history, last, pin, session, replay, diff, blob, gc) emit deterministic JSON. Large bodies are content-addressed.
  • Secrets use the OS keyring or XChaCha20-Poly1305 via FACET_SECRET_KEY.
Repository map
.agents/skills/facet/     # canonical agent skill (SKILL.md + Nushell CLI wrapper)
crates/facet/             # facet CLI binary (facet-cli)
crates/lattice/           # facet-lattice library (crates.io)
crates/facet-tui/         # Ratatui interface
crates/cli/               # upstream probe-cli
crates/core/              # upstream probe-core
docs/install.md           # install guide
docs/FACET.md             # Facet contracts

Status

0.8.1 on main (this release). 0.8.0 released (Oct 29, 2026). The facet-lattice crate is a separate version axis and does not follow the CLI: facet-lattice 0.5.9 is live on crates.io, with 0.5.8 still up (no yank).

  • facet-lattice: SQLite default. Scrubbed crate package published as 0.5.9.
  • CLI + TUI: shipped. Deterministic JSON, SQL over history, Ratatui interface.
  • Themes: user-defined theme files ship (facet theme check|list, themes/).
  • Roadmap: WebSocket, GraphQL, gRPC — IMPLEMENTATION_PLAN.md.

Contributing

Issues and pull requests welcome. Start with AGENTS.md and docs/FACET.md.

License

Upstream lineage: Probe (Apache-2.0). Facet-original crates (facet-cli, facet-lattice, facet-tui): MIT. See LICENSE and NOTICE.

About

API client optimized for humans and agents.

Resources

Stars

10 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages