[Docs]

Macaron docs

Install Macaron, start a session, and clean up AI-written code.

01Install

Macaron is in early access. It needs Bun. From the Macaron folder:

bun install
bun link

bun link puts the macaron command on your PATH.

03Start a session

cd your-project
macaron

Type what you need in plain language. Macaron shows each step as it works, for example ● Read(src/date.ts) or ● Bash(bun test), and streams its reply.

For a single task without a session:

macaron -p "add a test for parseDate and make it pass"

04Approvals

Before Macaron writes a file it shows the diff, and before it runs a shell command it shows the command. Both wait for y. Pass -y to approve everything, for scripts and CI. Macaron can only touch files inside the folder you started it in.

05Session commands

/deslop [path] scans for AI-code slop
/deslop fix [path] applies the safe fixes
/clear starts a new conversation
/cost shows token usage so far
/memory shows what Macaron remembers from earlier in the session; /memory compact moves older messages there now
/help lists commands, /exit quits

06Memory

Long sessions don't run out of room. Once the conversation passes about 30k tokens, the oldest turns become short dated notes that stay in context, and the raw messages leave it. When the notes pass about 40k tokens, they are condensed. A tool call is never separated from its result, and large tool output is left out of the notes.

Hooks let you watch or rewrite that process. Put them in ~/.macaron/memory-hooks.ts; Macaron only loads hooks from your home folder, never from a repository.

export default {
  // Before older messages are summarized: drop or trim what the notes shouldn't keep.
  beforeObservation: ({ messages }) => ({ messages }),
  // After: rewrite the new notes, e.g. strip anything that looks like a secret.
  afterObservation: ({ observations }) => ({
    observations: observations.replace(/sk-[A-Za-z0-9-]+/g, "[key]"),
  }),
  // Before and after the notes are condensed.
  beforeReflection: ({ observations }) => ({ observations }),
  afterReflection: ({ observations }) => ({ observations }),
  // Lifecycle events, for logging. They can't change anything.
  onObservationEnd: ({ usage, error }) => {},
};

Returning nothing passes the input through unchanged. If the summarizing model fails, Macaron keeps the full history and tries again next turn; if one of your hooks throws, the turn stops.

07What Macaron can do

List, Read and Search files (respecting .gitignore)
Edit and Write files, with a diff you approve
Bash: run shell commands such as tests and type checks, with approval, and a two-minute timeout
Deslop and DeslopFix: the rules below

08De-slop rules

De-slop finds common tells of AI-written TypeScript and JavaScript. It works without an API key:

macaron deslop src
macaron deslop --fix src --dry-run
macaron deslop --fix src

Rule	Finds	Fix
restating-comment	// Loop through the users, above the loop	Deletes the comment
rethrow-only-catch	try { … } catch (e) { throw e; }	Unwraps the try
bool-if-else-return	if (x) return true; else return false;	return x; (or Boolean(x) / !x)
placeholder-code	// ... rest of the code	Review only
leftover-console	console.log(user), console.log("here"), console.debug	Review only

A fix that would add a syntax error is rejected and the file is left as it was.

09Use in CI

macaron deslop exits with code 1 when it finds anything, so it can fail a pull request check. Add --json for machine-readable output and --rules to pick rules.

macaron deslop src --rules restating-comment,rethrow-only-catch