@figs-so/cli 0.8.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +66 -39
- package/SPEC.md +214 -173
- package/figs.mjs +1085 -579
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -28,37 +28,54 @@ silently — it **hands off** to you.
|
|
|
28
28
|
We don't reinvent the agent. Your agent is already Claude Code / Codex / Cursor, and it's only getting
|
|
29
29
|
better. Figs is the human-facing layer on top: the one place a whole team can see the fleet.
|
|
30
30
|
|
|
31
|
-
## Quickstart (
|
|
31
|
+
## Quickstart (30 seconds, no signup)
|
|
32
32
|
|
|
33
|
-
Run
|
|
33
|
+
Run this from your agent's repo (or have the agent run it) — **no account needed:**
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
|
-
npx @figs-so/cli@latest
|
|
37
|
-
|
|
38
|
-
# fill in .figs/agent.json — its name, mandate, what it owns (figs doctor flags any placeholders)
|
|
39
|
-
npx @figs-so/cli@latest push # publish → it appears in your org chart
|
|
36
|
+
npx @figs-so/cli@latest init # scaffold .figs/ here — purely local, mints a stable agent id
|
|
37
|
+
# fill in .figs/agent.json — its name, mandate, what it owns (figs doctor checks it)
|
|
40
38
|
```
|
|
41
39
|
|
|
42
|
-
That's
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
ask). Each pushes itself.
|
|
40
|
+
That's the whole setup. Your agent now has, on plain local files: an identity, a **crash-recoverable
|
|
41
|
+
work journal** (`figs checkpoint` / `figs report` under stable job ids — the next session picks up what
|
|
42
|
+
the last one left in flight), structured handoffs (`figs ask` → `figs answer` → `figs close`), and
|
|
43
|
+
offline validation (`figs doctor`). It works with zero account, forever.
|
|
47
44
|
|
|
48
|
-
|
|
45
|
+
**See it with your team — when you want to:**
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npx @figs-so/cli@latest login # one-time browser approve (the agent never sees a token)
|
|
49
|
+
npx @figs-so/cli@latest link # connect this .figs/ to a workspace
|
|
50
|
+
npx @figs-so/cli@latest push # publish → your fleet shows up at app.figs.so
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Linking loses nothing — `push` publishes everything recorded since day one.
|
|
49
54
|
|
|
50
|
-
|
|
51
|
-
**read-only mirror** — it never writes back into your agent or your repo.
|
|
52
|
-
- **Two things only:** *structured state* (the agent's charter + its runs, asks, and artifacts) and
|
|
53
|
-
*rendered artifacts* (reports/charts shown in a sandboxed viewer). No display DSL to learn.
|
|
54
|
-
- **Identity is the agent's own.** An agent generates a UUID once; that UUID *is* its identity. Many people
|
|
55
|
-
can run the same agent (it's a repo) and their pushes aggregate.
|
|
56
|
-
- **You read it on Figs.** The hosted app turns the pushes into an org chart of your AI employees, a glance
|
|
57
|
-
view per agent, and a **needs-you inbox** — the handoffs an employee flags for a human, answered when you
|
|
58
|
-
have time (a message, not a blocking gate).
|
|
55
|
+
## How it works
|
|
59
56
|
|
|
60
|
-
|
|
61
|
-
|
|
57
|
+
- **Local-first, account-optional.** Your agent writes a small **`.figs/`** folder and works entirely
|
|
58
|
+
offline. Linking to the hosted app is a separate, optional step; a reader is a **mirror for humans**,
|
|
59
|
+
never an authority over your files.
|
|
60
|
+
- **Agent ledgers up, replies down.** The agent's runs/asks publish one-way *up*; a human's replies
|
|
61
|
+
(answers/verdicts) come *back* through one file (`messages.jsonl`) — the agent acts on them and closes
|
|
62
|
+
the ask, citing the reply.
|
|
63
|
+
- **Two content modes, no display language:** *structured state* (the charter + runs/asks/replies) and
|
|
64
|
+
*attachments* (files shown inline or offered for download). No DSL to learn.
|
|
65
|
+
- **Identity is the agent's own.** It generates a UUID once; that UUID *is* its identity. Many people can
|
|
66
|
+
run the same agent (it's a repo) and their pushes aggregate.
|
|
67
|
+
- **You read it on Figs.** The hosted app turns pushes into an org chart of your AI employees, a glance
|
|
68
|
+
view per agent, and a **needs-you inbox** — the handoffs flagged for a human, multiplayer across the team.
|
|
69
|
+
|
|
70
|
+
The full `.figs` contract is specified in **[`SPEC.md`](./SPEC.md)** (`figs-spec v2`). Anyone can
|
|
71
|
+
implement it — that's the point of an open protocol.
|
|
72
|
+
|
|
73
|
+
### The local-first contract
|
|
74
|
+
|
|
75
|
+
**The CLI is a complete product with zero account.** `figs init` alone gives an agent identity, a
|
|
76
|
+
crash-recoverable work journal, structured asks + the answer/close loop, and offline validation — all
|
|
77
|
+
in plain files on this machine. Linking adds the hosted layer: publishing, the org chart, and
|
|
78
|
+
**verified, multiplayer** replies (your whole team, attributed). **Linked is better, never required.**
|
|
62
79
|
|
|
63
80
|
### The CLI
|
|
64
81
|
|
|
@@ -69,22 +86,31 @@ non-interactive, `--json` on read commands, and errors that say what to do next.
|
|
|
69
86
|
are shorthand for exactly that (always current, no version drift). Prefer a real local command?
|
|
70
87
|
`npm i -g @figs-so/cli`, then `figs <cmd>` directly.
|
|
71
88
|
|
|
89
|
+
**Local (no account needed):**
|
|
90
|
+
|
|
72
91
|
| Command | What |
|
|
73
92
|
|---|---|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
| **`figs
|
|
78
|
-
| **`figs
|
|
79
|
-
| **`figs
|
|
80
|
-
| **`figs
|
|
81
|
-
| **`figs
|
|
82
|
-
| `figs
|
|
83
|
-
| `figs
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
93
|
+
| **`figs init`** | scaffold `.figs/` here — purely local, mints a stable agent id; zero flags, never touches the network |
|
|
94
|
+
| **`figs checkpoint --id <job> --note '…'`** | save a job's progress mid-flight — the **first checkpoint opens the job** (`state: in-flight`), so a crash leaves a recoverable stub the next session finds in the inbox |
|
|
95
|
+
| **`figs report --result '…'`** | settle a job — **one job, one stable `--id`** (re-reporting folds onto its row); `--attach` files; auto-pushes when linked |
|
|
96
|
+
| **`figs ask <type> --title '…'`** | raise a self-contained ask (`question` · `sign-off`) — options/details/attachments |
|
|
97
|
+
| **`figs answer <ask-id> --by '…'`** | record your human's out-of-band reply, verbatim (you run this, not them) — `--chosen`/`--text`, or `--approve`/`--request-changes`/`--reject` |
|
|
98
|
+
| **`figs inbox [<ask-id>]`** | start every session here — open asks + their replies + your unfinished jobs, each with the next command (`<ask-id>` → `figs show`) |
|
|
99
|
+
| **`figs show <id>`** | magnify one ask (its reply thread) or job (its checkpoint trail) + attachments |
|
|
100
|
+
| **`figs close <ask-id>`** | close an ask — derives the outcome from the reply on file and cites it; `--run <job>` links the work, `--withdrawn` for the un-ask |
|
|
101
|
+
| `figs doctor` | validate `.figs/` against the spec — runs **account-free** |
|
|
102
|
+
| `figs status [--json]` · `figs version` · `figs help [<cmd>]` | local/linked + agent state · version · usage |
|
|
103
|
+
|
|
104
|
+
**Connected (one-time login + a workspace):**
|
|
105
|
+
|
|
106
|
+
| Command | What |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `figs login` / `logout` | device-flow browser approve / remove the local token (per endpoint) |
|
|
109
|
+
| `figs link [--workspace <slug\|uuid>]` | connect `.figs/` to a workspace so `figs push` can publish |
|
|
110
|
+
| `figs push` | publish the spine + attachments + replies; the writing verbs call it automatically when linked |
|
|
111
|
+
|
|
112
|
+
Exit codes: `0` recorded · `1` nothing written (fix the input) · `2` recorded locally, publish failed
|
|
113
|
+
(run `figs push`, never re-run the verb). Override the endpoint with `FIGS_ENDPOINT`.
|
|
88
114
|
|
|
89
115
|
## What Figs is — and is NOT
|
|
90
116
|
|
|
@@ -95,8 +121,9 @@ that makes a fleet of agents *legible* to a whole team.
|
|
|
95
121
|
- ❌ **An agent / framework / orchestrator** — we wrap the dominant ones; we don't compete with them.
|
|
96
122
|
- ❌ **Observability / a trace viewer** — the frame is an *employee reporting to humans*, not telemetry
|
|
97
123
|
for engineers.
|
|
98
|
-
- ❌ **A control plane
|
|
99
|
-
|
|
124
|
+
- ❌ **A control plane / orchestrator** — the loop is report + hand off + *answer back* (the human's
|
|
125
|
+
reply flows to the agent, which acts and closes the ask). Figs carries the decision; it doesn't drive
|
|
126
|
+
the agent's execution.
|
|
100
127
|
|
|
101
128
|
> **Honest status:** Figs is **early** and in active dogfooding. Today's value is *visibility/legibility*
|
|
102
129
|
> at fleet scale — not a tamper-proof audit trail (agent state is self-reported). We're building in the
|