Beta Coming soon. This feature is still being built, so names and details may change before it ships.

Habits

Habits are a folder, .ingot/habits/, with one Markdown file per type of fix: bug.md, defect.md, design.md, performance.md, tests.md, security.md, refactor.md, general.md, and any type you add. Each file holds lasting knowledge for future runs: decisions, patterns and "always do X when Y", one bullet per entry. The agent reads the files that fit the task and appends what it learns to the matching one. Commit the folder and your whole team's agents learn together.

Beta Habits is an optional feature and is off until you turn it on. While it is off the agent neither reads nor writes the folder; the files stay where they are. Rules say how to write code; habits are what the agent learned about working in this project.

The Ingot Habits page in Settings: Knowledge by type with the .ingot/habits/ folder, bug.md with 2 entries and the other default type files, and + Add typeThe Ingot Habits page in Settings: Knowledge by type with the .ingot/habits/ folder, bug.md with 2 entries and the other default type files, and + Add type
The Ingot Habits page in Settings: Knowledge by type with the .ingot/habits/ folder, bug.md with 2 entries and the other default type files, and + Add type

Turn it on

Habits is easy to find in three ways, like every optional feature:

  • A suggestion in the chat. When your prompt states something lasting ("From now on, always add a regression test when fixing a crash"), describes a routine ("every time we release: bump the version, update the changelog, then tag the commit"), or the project already has team habits while Habits is off, a small card above the chat box offers Enable Habits. × hides it for good.
  • Settings › Features › Habits. An on/off switch. The same switch is Use habits at the top of the Habits page.
  • The Habits button in the status bar. One click turns Habits on and opens the Habits page; it looks dimmed while Habits is off. The shortcut is ⌥⇧⌘` on macOS and Ctrl+Alt+Shift+` on Windows and Linux, and Habits: Turn On and Open and Habits: Turn On or Off are in Find Action.

Turning Habits on creates .ingot/habits/ with the default type files that are missing. It never overwrites a file, and while Habits stays on a type file you delete stays deleted.

The Habits button in the Ingot status bar, turned onThe Habits button in the Ingot status bar, turned on
The Habits button in the Ingot status bar, turned on
Ingot Settings, Features page with the Habits switchIngot Settings, Features page with the Habits switch
Ingot Settings, Features page with the Habits switch
The Ingot Habits page with Use habits off: a note says the agent does not read or write habitsThe Ingot Habits page with Use habits off: a note says the agent does not read or write habits
The Ingot Habits page with Use habits off: a note says the agent does not read or write habits

The type files

FileWhat goes in it
bug.mdBug fixes: something crashes, throws or gives the wrong result
defect.mdDefects against the spec: it works, but not as the ticket or acceptance criteria say
design.mdUI and UX: layout, styling, theming, icons, accessibility
performance.mdSpeed and resources: latency, memory, rendering, caching, bundle size
tests.mdUnit and end-to-end tests: what to cover, how to write them, flaky tests
security.mdSecrets, auth and input handling: never leak, always validate
refactor.mdRestructuring without changing behavior: naming, extraction, duplication, dead code
general.mdEverything else worth keeping: project conventions, workflow, decisions

A type file is plain Markdown. The frontmatter says what the type is about; the keywords decide which tasks it fits. Every - bullet in the body is one entry.

---
description: Bug fixes: something crashes, throws or gives the wrong result.
keywords: [bug, crash, broken, error, exception, regression, stack trace, throw, null, undefined, fail]
---
# Bug

Lasting knowledge for future runs. One bullet per entry.

- Always add a regression test before fixing a crash
- Reproduce it in a failing test first

Your own types work the same way: i18n.md with keywords: [locale, translation] is read for translation work.

How the agent reads them

For every request Ingot scores each type file that has entries against your prompt: the type's name counts 2 points and each of its keywords 1. The agent gets the entries of the best 3 types (at most the last 30 entries of each) and of general.md, which it always reads. It also gets the list of all type files with their entry counts, so it can open another one when the task turns out to touch it.

For "Another crash on the cart page" the agent reads bug.md; for "Make the header spacing tighter" it reads design.md, and the crash knowledge stays out of the prompt.

How the agent writes to them

When the agent learns something worth keeping, it adds a line to its reply:

HABIT: [bug] Always add a regression test before fixing a crash
HABIT: Never log access tokens in the payment client

Ingot takes those lines out of the reply and appends each one to its type file. A named type goes to that file (a new name creates a new file); without a type Ingot classifies the entry with the same scoring, so the second line lands in security.md. An entry already in the file is not added twice, and lines inside code blocks are left alone.

Each save shows a silver Saved to Habits note in the chat with the file and the entry. Click the note to see the file on the Habits page, Open opens it in an editor tab, and Undo takes the entry back out of the file.

To let the agent read the files but never write them, turn off Agent adds what it learns to the type files on the Habits page (ingot.habits.knowledge.autoSave).

Edit the files on the Habits page

Settings › Tools › Habits lists the folder under Knowledge by type: each file with its description and entry count. Click a file to edit it right there; the count updates as you type. The arrow icon opens it in an editor tab instead. Escape or Cancel closes the editor without saving.

bug.md open on the Ingot Habits page: the .ingot/habits/bug.md editor with its frontmatter and 2 entriesbug.md open on the Ingot Habits page: the .ingot/habits/bug.md editor with its frontmatter and 2 entries
bug.md open on the Ingot Habits page: the .ingot/habits/bug.md editor with its frontmatter and 2 entries

+ Add type makes a new type file. Use letters, numbers and dashes; Bugs is refused when bug.md is already there.

Add type on the Ingot Habits page: migrations typed in the name field next to .md, with Cancel and AddAdd type on the Ingot Habits page: migrations typed in the name field next to .md, with Cancel and Add
Add type on the Ingot Habits page: migrations typed in the name field next to .md, with Cancel and Add

Keep knowledge from your prompt

When your prompt says something lasting while Habits is off, the suggestion names the file it belongs in: Keep this in .ingot/habits/bug.md so the agent follows it in every future run. Enable Habits turns Habits on, saves the sentence (without "From now on" or "please") to that file and opens it on the Habits page.

The Habits suggestion card above the Ingot chat box: Keep this in .ingot/habits/bug.md so the agent follows it in every future run, with Enable Habits and a close buttonThe Habits suggestion card above the Ingot chat box: Keep this in .ingot/habits/bug.md so the agent follows it in every future run, with Enable Habits and a close button
The Habits suggestion card above the Ingot chat box: Keep this in .ingot/habits/bug.md so the agent follows it in every future run, with Enable Habits and a close button

Scenario playbooks

The same folder can also hold playbooks: files with when and steps frontmatter for a scenario such as a payments bug or a release. When this kind of task comes up, do these steps, use these tools, and don't stop until these checks pass. The Habits page lists them under Scenario playbooks, below the type files.

The Ingot Habits page: Use habits on, the type files and a Release playbook under Scenario playbooksThe Ingot Habits page: Use habits on, the type files and a Release playbook under Scenario playbooks
The Ingot Habits page: Use habits on, the type files and a Release playbook under Scenario playbooks

When the suggestion came from a routine in your prompt, Enable Habits opens a playbook drafted from it: the scenario becomes when and the name, and each step ("…, then …", a numbered list, or the part after a colon) becomes a step. Edit it, pick This project or Global, and click Add habit.

The Habits suggestion card above the Ingot chat box: Save steps like these as a habit, with Enable Habits and a close buttonThe Habits suggestion card above the Ingot chat box: Save steps like these as a habit, with Enable Habits and a close button
The Habits suggestion card above the Ingot chat box: Save steps like these as a habit, with Enable Habits and a close button
A playbook drafted from a chat prompt on the Ingot Habits page: name Release, when, and the steps bump the version, update the changelog and tag the commitA playbook drafted from a chat prompt on the Ingot Habits page: name Release, when, and the steps bump the version, update the changelog and tag the commit
A playbook drafted from a chat prompt on the Ingot Habits page: name Release, when, and the steps bump the version, update the changelog and tag the commit

A playbook file

---
name: Payments bug
when: A bug report or failing test in the payments service
keywords: [payment, checkout, refund, invoice]
globs: ["services/payments/**"]
errorRegex: "PaymentError|CardDeclined"
steps:
  - Reproduce the problem with a failing test in services/payments/test
  - Search the service logs and recent commits for the error
  - Fix the cause, not the symptom
  - Run the payments test suite
allowedTools: [read_file, grep, glob, edit_file, ingot/run]
doneCriteria:
  - The new test fails before the fix and passes after it
  - npm test -w services/payments passes
---
Payments code handles money: never change rounding or currency logic without a test.
FieldMeaning
nameshown in the chat (up to 64 characters)
whenthe scenario, in plain words; the agent reads it to decide if the playbook fits
keywordswords in your prompt that point to this playbook
globsfiles in context that point to this playbook
errorRegexan error pattern to look for in your prompt, attachments, diagnostics and terminal output
stepsthe ordered checklist the agent follows (up to 20)
allowedToolstools the agent may use while the playbook is active, such as read_file, ingot/run or github/*; leave it out to allow all
doneCriteriachecks the agent confirms before it finishes

Text after the frontmatter is sent along with the steps as extra notes. A file with when or steps is always a playbook, never a type file.

Where playbooks live

FolderScope
.ingot/habits/*.mdthis project; shared through Git
~/.ingot/habits/*.mdevery project on this machine
.cursor/habits/*.mdread for compatibility

On a name clash the project wins over .cursor/habits, which wins over the global folder. Turning a team playbook off for yourself is a personal setting; it does not change the committed file. Type files are only read from the project's .ingot/habits/.

Habits work in any project layout. When you open a subfolder of a repository, the playbooks in .ingot/habits of the folders above it, up to the repository root, are followed too; the open folder's own win a name clash and new habits are saved there. If a habit seems ignored, Help › Ingot Health… › Project setup says whether Habits is off (with a Turn on Habits button) or a habit file did not load.

Auto-matching

For every new request Ingot scores each playbook against what you're working on:

SignalPoints
errorRegex matches an error in the prompt, attachments, diagnostics or terminal3
a keywords word appears in the prompt2
a file in context matches globs1

The best playbook with at least 2 points is picked, so a matching file alone never picks one. The agent can also switch playbooks on its own when the task turns out to be something else, and you can pick or turn off a playbook yourself.

The "Using habit" pill

When a playbook is active, a pill above the composer shows Using habit: Payments bug and why it was picked (for example keyword "refund"). Open it to see the live checklist: the agent ticks steps as it goes, and before it finishes it checks the done criteria and is reminded once if one is still open. Choose Habit off to stop following it for this chat.

Save a run as a habit

After the agent solves something you'll see again, choose Save as habit on the finished run. Ingot drafts a playbook from what actually happened:

  • steps from the tool calls in the run (up to 10; consecutive reads are folded into one step)
  • keywords and globs from your prompt and the files it edited
  • doneCriteria from the checks it ran, such as tests, lint or build

Review the draft, edit it, and save it to the project or to your global habits.

Settings

SettingDefaultWhat it does
ingot.habits.playbooks.enabledfalseHabits (Settings › Features, and Use habits on the Habits page): the agent reads the type files that fit the task and follows matching playbooks. Off, the files stay but the agent ignores them and Save as habit is hidden
ingot.habits.knowledge.autoSavetrueAgent adds what it learns to the type files: HABIT: lines in replies are appended to .ingot/habits/<type>.md. Off, the agent only reads the files
ingot.habits.playbooks.autoSelecttruePick a matching playbook automatically from its keywords, globs and error pattern. Off, a playbook is only used when you or the agent pick one
ingot.habits.playbooks.disabled[]Playbooks you turned off for yourself on the Habits page, as ids like project:payments-bug; the committed files do not change
ingot.habits.enabledfalseLearn habits: notice what you repeat and offer to turn it into a rule, command or hook
ingot.habits.threshold3How many times a pattern repeats before Ingot suggests it

From the terminal

ingot habits reads and writes the same folder as the Habits page, so you can manage it in scripts and CI. It never calls a model.

npx @ingotide/cli habits                                   # the type files with entry counts, and the playbooks; --json
npx @ingotide/cli habits init                              # create the default type files that are missing
npx @ingotide/cli habits add "Always add a regression test before fixing a crash"
# Added to .ingot/habits/bug.md (bug: keyword "crash", keyword "regression"): …
npx @ingotide/cli habits add "Use the shared date helper" --type refactor
npx @ingotide/cli habits classify "Never log access tokens"   # .ingot/habits/security.md (keyword "access token")
npx @ingotide/cli habits relevant "the checkout crashes on an empty cart"   # the files and text the agent gets
npx @ingotide/cli habits read bug                          # print one type file
npx @ingotide/cli habits new-type i18n --keyword locale --keyword translation
npx @ingotide/cli habits types                             # descriptions, keywords and entry counts; --json

For playbooks:

npx @ingotide/cli habits show "Payments bug"               # the steps, tools and done criteria
npx @ingotide/cli habits new "Release" --when "Shipping a release" \
  --step "Bump the version" --step "Update the changelog" --step "Tag the commit" --keyword release
npx @ingotide/cli habits validate                          # exits 1 when a playbook file has errors; in CI
npx @ingotide/cli habits match "refund fails with CardDeclined" --file services/payments/refund.ts
npx @ingotide/cli habits prompt "Release"                  # what the agent gets while the playbook is active
npx @ingotide/cli habits remove "Release"

new also takes --glob, --error, --tool, --done and --notes, writes to ~/.ingot/habits with --global, and refuses to overwrite a playbook without --force. match scores playbooks like the IDE; add --error-line for terminal output.

Learned habits

Separately from the folder, Ingot can notice what you repeat and offer to save it. Turn on Learn habits in Settings › Tools › Habits (off by default).

It noticesExample card
the same instruction in your promptsYou often ask to use the shared Button component.
the same terminal commandYou often run npm test.
agent edits you keep rejectingYou often reject edits that add console.log calls.

After a pattern repeats 3 times (setting ingot.habits.threshold), a card appears in the chat with Make it a rule, Make it a command, Make it a hook (for commands) and Not now. Saving writes a normal file you can edit: a rule in .ingot/rules/, a slash command in .ingot/commands/, or a stop hook in .ingot/hooks.json.

---
description: Learned habit: ask to use the shared Button component
alwaysApply: true
---
Use the shared Button component.

What Ingot has learned is kept in .ingot/habits.json in the project. It is git-ignored and never leaves your machine.

The Saved to Habits note

Beta Whenever something is saved to your habits, a small silver note appears in the open chat instead of a pop-up:

Saved to Habits
It appears whenDetail on the note
the agent adds an entry to a type filebug.md: Always add a regression test before fixing a crash
a pattern reaches the thresholdLearned: use the shared Button component
you choose Make it a rule, Make it a command or Make it a hookuse the shared Button component → .ingot/rules/use-the-shared-button-component.md
you save a playbookPayments bug → .ingot/habits/payments-bug.md

Click the note to open it on the Habits page in Settings, where it is highlighted; a type file opens in the editor.

Undo on the note takes the save back:

Undo afterResult
an entry in a type filethe entry is removed from the file; the rest of the file stays
a learned patternthe pattern is forgotten
Make it a rule or Make it a commandthe file is deleted (only if this save created it) and the suggestion card comes back
Make it a hookthe command is removed from stop in .ingot/hooks.json
saving a playbookthe playbook file is removed

The note then reads Removed from Habits. Notes only appear while a chat is open; learned patterns also need Learn habits turned on.