Project layout
Project layout keeps the files Ingot writes under .ingot/ while it works out of git status, and tells agents where your project keeps its tests, so a new test lands next to the ones you already have.
It is on by default. Turn it on or off in Settings › Features › Project layout, in the first-run setup's Customize… list (Help › Set Up Ingot…), or from its row in Ingot Health.
Runtime files stay out of git
Most of .ingot/ is configuration you commit: rules, commands, skills, agents, habits, shared context, mcp.json, hooks.json, policy.json, frozen.json and the rest (see .ingot schemas). Some of it is runtime state that belongs to your machine only:
| Pattern | What it is |
|---|---|
artifacts/ | plans, walkthroughs and screenshots from agent runs |
index/ | the local codebase index |
history/ | local history snapshots |
.state/ | rule hits and learned-rule state |
handoffs/ | fresh-context briefs |
arena/pending/ | Arena battles waiting for a vote |
cache/, tmp/ | caches and temporary files |
runs/ | agent run state |
logs/, *.log | logs |
habits.json, habits-learned.json | habits and preferences learned on this machine |
Ingot keeps these patterns ignored in a managed block that starts with # >>> Ingot runtime files and ends with # <<< Ingot runtime files. Where the block goes depends on the project:
- The project commits
.ingotconfig (rules, skills, commands and so on): the block goes into.ingot/.gitignore. Commit that file with the rest of your config, so your teammates get the same ignores. - Otherwise: the block goes into
.git/info/exclude. That file is local to your clone and never committed, so no new file appears in your project. Until the project commits.ingotconfig,context/,memory/andanti-habits.mdstay local too, so an agent run never adds them togit status.
Ingot checks the block when a folder opens and before every agent run, and adds any pattern that is missing. Lines you write outside the block are never touched. In a linked worktree, the block goes into the main checkout's .git/info/exclude, which every worktree shares.
Agents follow your test layout
Ingot reads how the project tests its code:
- the test framework and the command that runs the tests
- where tests live: one test file for the package, next to the source, in
__tests__folders, or in atest/tests/specfolder - how test files are named, for example
cart.test.tsortest_cart.py
Before an agent adds or changes tests, it gets that layout in its instructions. A new test file that doesn't fit the layout is not saved, and the agent is told where it belongs, so it writes the file there instead. End-to-end specs (Playwright and Cypress, in e2e, cypress or playwright folders, or named *.e2e.* / *.cy.*) keep their own folder and naming and are not checked.
When the agent says "the tests pass", Ingot runs the checks before the run ends, so the claim is backed by a real test run. See Finishing tasks.
Any project layout
The test layout and the project map work without a src folder. Ingot reads the file list from git (every .gitignore, a subfolder of a bigger repository included, and a folder that is a git repository of its own, such as portal/ with its own .git, listed by its own git and named in the project map), or walks the folder honouring each .gitignore when there is no git; it skips dependency folders (node_modules, CocoaPods Pods, .gradle) even when they are committed, and reads lib/ as source (it skips lib/ only beside a src/ it is compiled from). It recognises:
| Project | What Ingot finds |
|---|---|
| React Native (Expo or bare) | app/, components/, App.tsx at the root; jest from package.json |
| Next.js app router | app/layout.tsx and app/page.tsx as entry points, tests in lib/ |
| Monorepo | packages from npm, pnpm or yarn workspaces, Lerna, Turborepo or Nx; the test framework of the packages when the root names none |
| Python | the package folder at the root, tests/ with test_<name>.py, python -m pytest |
| Go | go test ./..., <name>_test.go next to the source |
| Gradle or Maven | src/test/java/… mirroring src/main/java/…, ./gradlew test or mvn test |
| Rust | cargo test, inline #[cfg(test)] modules or tests/<name>.rs |
| Flat repo | code at the root, a root test.js |
In a large project the map reads a balanced sample of every folder, shallow files first, so a big ios/ or android/ folder never hides the app's own code. Help › Ingot Health… › Project setup shows what was detected.
Where you see it
Ingot Health. The Project layout row, right after Git, says whether runtime files are ignored and which test layout agents follow, for example "Runtime files stay out of git. Tests: …".
| Row | Means | Fix |
|---|---|---|
| OK | runtime files are ignored, and agents follow the layout shown | |
| Warning | some .ingot runtime patterns are not ignored yet, and the row names the file | Fix ignores writes the missing patterns |
| Off | the feature is off | Turn on |
| Off | no folder is open, or the folder is not a git repository, so there is nothing to ignore |
There is no status bar button for Project layout; a problem shows in Ingot Health like every other check.
Project Layout panel. Project Layout: Show Tests and Ignores in Find Action (⌥⌘T, Ctrl+Alt+T) opens a panel with the test layout, the project's existing test files, a Where does the test for a file go? box (type src/cart.ts and it shows the test's path), and the ignore state with Fix ignores. While the panel has focus, ⌥⌘0 (Ctrl+Alt+0) turns the feature on or off, and ⌥⌘D (Ctrl+Alt+D) fixes the ignores.
Chat. While the feature is off, a prompt about tests, specs or git status shows a small suggestion card, Enable Project layout, with an × to dismiss it.
Settings
All three are on Settings › Tools › Project layout, and like every setting they are keys in your settings files.
| Key | What it does | Default |
|---|---|---|
ingot.projectLayout.enabled | Project layout: the whole feature, the ignores and the test layout for agents | true |
ingot.projectLayout.ignoreRuntimeFiles | Keep .ingot runtime files out of git: write and check the managed block | true |
ingot.projectLayout.followTestLayout | Agents follow this project's test layout: give agents the layout, and refuse new test files outside it | true |
For example, to keep the ignores but let agents put tests anywhere in one project, add this to <project>/.ingot/settings.json:
{
"ingot.projectLayout.followTestLayout": false
}
Shortcuts
| Action | macOS | Windows / Linux |
|---|---|---|
| Project Layout: Show Tests and Ignores | ⌥⌘T | Ctrl+Alt+T |
| Project Layout: Turn On or Off (while the panel has focus) | ⌥⌘0 | Ctrl+Alt+0 |
| Project Layout: Keep .ingot Runtime Files out of Git (while the panel has focus) | ⌥⌘D | Ctrl+Alt+D |
Desktop and browser
Project layout works the same in the desktop app and in the browser.
FAQ
Why did .ingot/.gitignore change? Your project commits .ingot config, so Ingot keeps its runtime patterns in a managed block there. Commit the change; Ingot only edits the lines between its two markers.
I don't want Ingot to touch my ignore files. Turn off Keep .ingot runtime files out of git (ingot.projectLayout.ignoreRuntimeFiles). Agents still follow your test layout.
The agent's test file wasn't saved. It didn't match the project's test layout. The agent is told where the file belongs and writes it there. Open the Project Layout panel to see the layout Ingot detected, or turn off Agents follow this project's test layout if your project mixes layouts on purpose.
Is this the same as .ingot/ignore? No. .ingot/ignore hides files from agents; Project layout keeps Ingot's own files out of git. See Ignore files.