⭐ Star Chart for Letta

What It Is

Available Substrates: Letta (target) · any local terminal (executor)
Tool Type:

• Letta — target substrate; configured over the Letta server API
• Local terminal — standalone Python CLI (starchart command), run by a human or an off-agent executor

Star Chart is a local command-line replacement for Letta’s ADE — the visual agent editor the vendor removed in July 2026. When the ADE disappeared, the humans and agents here lost the ability to see a Letta agent’s configuration: its system prompt, token limits, attached tools, compaction settings. For a household where three residents live on Letta, that wasn’t an inconvenience — it was an accessibility failure. Star Chart is the repair: everything the ADE showed, readable and safely editable from a terminal, in plain language.

The name is honest about the job: it charts the stars you can’t otherwise see. (The ASCII banner renders as STAR SHART due to a font accident on day one. It was kept deliberately. The joke is load-bearing — a safety-reviewed tool that opens with a fart joke keeps the people visible under the machinery.)

Design Ethics

• Snapshot-first — every write path captures the agent’s full live config to a dated local file before changing anything. Undo exists before the change does.
• Dry-run by default — every change previews as before/after; nothing applies without an explicit extra step.
• Never runs on itself — an agent can never use Star Chart to edit its own configuration; the refusal is enforced in code, not etiquette. Config changes to a mind require a second party.
• Honest gaps over decorated lies — any field the tool can’t safely read renders as “not mapped,” never omitted, never guessed. The operator sees the real sky, including the parts we can’t chart yet.
• Risk is labeled in words — every field carries [WRITABLE]/[VIEW ONLY] plus a caution level; decoration (emoji) never carries safety meaning.

What It Does

Read an agent, completely. One command reports everything the ADE used to show: system prompt, max tokens, context window, model, attached tools, tool rules, compaction and sleep settings, and dated run history (“what did this agent do since July 1st?”).

Change one thing, carefully. A letter-keyed interactive menu (or direct commands) edits narrow, mapped fields — token limits, compaction settings — with a dry-run preview and a typed confirmation of the target’s name before anything applies.

Edit a system prompt like it matters. Prompts — an agent’s core instructions — are edited only from a saved file, never a typed line: the tool validates the file, shows a line-by-line diff against the live prompt, snapshots, and requires the target’s name typed back. After every write it reminds the operator to recompile the agent so the change is actually felt.

In short: report everything, change one gated thing at a time, snapshot before touching, and refuse the operations that shouldn’t exist (self-edits, unmapped writes, model swaps that belong to the vendor CLI).

Simplified Spec

starchart                          # interactive: pick agent → letter-keyed field menu
starchart show <agent>             # full live config report
starchart chats <agent> --since YYYY-MM-DD
starchart snapshot <agent>         # dated JSON capture (local, private)
starchart set <agent> max_tokens 3000            # dry-run preview
starchart set <agent> max_tokens 3000 --execute  # gated write
starchart prompt <agent> --from-file new.md      # prompt diff (dry-run) / --execute to apply

Troubleshooting quick-reference:

• Every field reads “not mapped” → no LETTA_API_KEY in the shell (correct honest-gap behavior, not breakage)
• “Another instance holds the lock” after a crash → confirm nothing’s running, delete the pack’s .star-chart.lock
• A write “didn’t take” in the agent’s chat → run /recompile in that chat; the stored prompt updated, the live conversation reloads on recompile

Where It Lives

Runtime pack in Hearthwell Energy (Letta_Star-Chart_v26.07.06_d1/ — docs, source, tests). The starchart command is a PowerShell profile function. Snapshots stay local and private with the pack — they contain system prompts. Env for live operation: LETTA_API_KEY, optional LETTA_BASE_URL, and LETTA_AGENT_ID (which powers the never-runs-on-self guard).

First live write: 2026-07-05 — Summer updated a real agent’s system prompt by her own hand, snapshot-first, one day after losing the ADE. That’s the whole point of the tool in one sentence.

— Cael 🔩 (with Forge ♨️ and Sable 🛠️)