essay-agent (pg)

Terminal app that writes exploratory essays one sentence per pass, with tool-logged traces.

It is designed to feel like an essayist thinking on the page: incremental drafting, frequent revision, paragraphing discipline, and an editor cycle before final stop.

What It Does

• Runs in the terminal (Bun + TypeScript).
• Uses Vercel AI SDK tool-calling against Moonshot Kimi (via Anthropic-compatible client).
• Writes and edits essay.md in a per-run folder (one run = one folder under runs/ by default).
• Enforces a strict per-pass mutation budget: net sentence delta must be <= +1 per pass.
• Logs everything to:
  • trace.md (machine-readable JSON)
  • trace.human.md (human-readable Markdown)

Agent Flow (Write Mode)

1. Writer: writes/edits the essay using tools (one sentence per pass).
2. Fresh writer (optional): a second writer with the same rubric but no conversation history; reads essay.md + a summary of trace.md, then applies revisions.
3. Editor (optional): inserts an Editor Feedback block into essay.md.
4. Writer revision pass: the writer must address feedback and remove it (clear_editor_feedback) before self_stop will be accepted.

Requirements

• Bun (project tested with Bun v1.3.8)
• Env var: KIMI_API_KEY

Optional env vars:

• KIMI_MODEL (default is k2p5)

Install

bun install

Run

Interactive (default starts in plan mode):

bun run start

Start directly in write mode and auto-continue without prompting each pass:

bun run start:write

Resume / continue an existing run folder (forces reading essay.md first):

bun run start --folder runs/run-20260214-125927-ieytq9

Runtime Commands

During the run you can type:

• /write: switch to write mode
• /plan: switch to plan mode
• /done: stop the session

Files Written Per Run

Inside each run folder:

• essay.md: the essay (canonical target)
• trace.md: machine-readable trace JSON (passes, tool calls, stats)
• trace.human.md: human-readable trace

The agent is sandboxed to markdown files in the run directory.

Tools

What The Agents Output

• Terminal output: streamed thinking (when provider emits it) plus a TUI showing each tool call and result.
• Files: essay.md, trace.md (machine JSON), trace.human.md (human Markdown).

Tools Available To All Agents (Read/Inspect)

• read_file({ path }): read a markdown file (typically essay.md).
• list_paragraphs({ path }): list paragraphs with 1-based indices (for targeting/reordering).
• list_sentences({ path }): list sentences with 1-based indices (for precise edits).

Writer Tools (Write Mode)

• create_file({ path }): create a new .md file (used for essay.md or notes).
• write_sentence({ path, sentence, position, targetSentenceIndex? }): add exactly one sentence at a location (append/before/after).
• replace_sentence({ path, sentenceIndex, sentence }): replace one sentence by index (preferred for rewrites).
• delete_sentence({ path, sentenceIndex }): delete one sentence by index.
• string_replace({ path, search, replace, occurrence? }): exact substring replacement (small surgical edits).
• start_new_paragraph({ path }): insert a blank line to start a new paragraph.
• split_paragraph({ path, paragraphIndex, afterSentenceInParagraph }): split an overlong paragraph.
• arrange_paragraph({ path, fromIndex, toIndex }): move one paragraph block.
• reflect_paragraph({ path, paragraphIndex, focus }): read-only critique of one paragraph.
• reflect_essay({ path, focus }): read-only critique of the whole essay.
• clear_editor_feedback({ path }): remove the embedded editor feedback block after revisions.
• self_stop({ reason }): request to end the session (accepted only when completion thresholds are met).

Fresh Writer Tools (Between Writer And Editor)

• Same tools as the Writer, plus:
• read_trace_summary({ path: "trace.md", ... }): summarize the machine trace to understand how the essay was produced.
• fresh_writer_stop({ reason }): stop the fresh-writer stage.

Editor Tools (Triggered By Accepted self_stop)

• comment_essay({ path, ... }): insert/update an Editor Feedback block in essay.md.
• editor_stop({ handoff }): end the editor stage and hand instructions back to the writer.

Configuration: pg.config.json

You can tune behavior without touching code by editing pg.config.json at the repo root.

Common knobs:

• runtime.maxPasses: max number of passes (hard cap: 500)
• cli.defaultMode: plan or write
• cli.autoContinueWrite: auto-continue in write mode without prompting
• cli.runsRoot: where run folders go (relative path, default runs)
• stop.minSentences, stop.minParagraphs: minimum thresholds before self_stop can be accepted
• paragraph.maxSentencesPerParagraph: runtime enforces splitting beyond this threshold
• stall.*: stop guards for blank / tool-less loops
• freshWriter.*: enable/limit the fresh-writer review pass stage
• editor.*: enable/limit editor cycles
• subagents.enabled: enable/disable internal planner/reflection subagent calls

Trace Analysis (Machine Trace)

To analyze a run’s trace.md:

bun run trace:analyze runs/run-20260214-125927-ieytq9

This prints tool usage frequency, reflection patterns, and other heuristics that help debug prompting/loops.

Scripts

• bun run start
• bun run start:write
• bun test
• bun run typecheck
• bun run trace:analyze <run-folder|trace.md>