tcode.md
A file named tcode.md, placed anywhere in or above your project folder, is read automatically and given to tAI as standing background on every turn, so conventions and context you would otherwise have to repeat in every session only need to be written down once.
| Where tCode looks | When it's loaded |
|---|---|
| Current folder, then every parent folder above it, up to the filesystem root | Once, the first time it's needed after tcode starts |
tCode checks the folder you started it in first, and if there is no tcode.md there, walks upward through every parent folder until it finds one or runs out of parents. This means a single tcode.md at the root of a large repository is picked up automatically no matter which subdirectory you actually run tcode from, without needing a copy in every subfolder.
Whatever the file contains is inserted into the background information tAI has for every message in the session, labeled clearly as coming from tcode.md so it is never confused with something you actually typed. It is not a command and does not run anything on its own; it is plain text context, exactly as if you had pasted it at the start of the conversation yourself, except you only have to write it once.
What to put in it
The most useful content is the kind of thing you would tell a new engineer joining the project in their first week: which package manager the project uses and why, where configuration actually comes from, a naming convention that is not obvious from the code alone, a subsystem that looks like it could be touched casually but actually cannot, a test command that is not simply "run the test runner." Anything you find yourself repeating across different conversations about the same project is a good candidate to move into the file instead.
# tcode.md ## Commands - Install: `pnpm install` (not npm, the lockfile is pnpm-specific) - Test: `pnpm test -- --run` (the default watch mode hangs in tCode) - Lint: `pnpm lint` ## Conventions - API routes live in `src/api/`, one file per resource, not grouped by verb - Database migrations are hand-written, there is no ORM auto-generation - Never edit files under `generated/`, they are rebuilt from `schema.graphql`
A short, specific file is more useful than a long, general one. Restating good general engineering practice does not help, since that is already how tCode approaches unfamiliar code by default; what actually helps is the handful of facts specific to this one project that nothing in the code itself would reveal on a first read.
Loaded once per session
tcode.md is read a single time, the first time it is needed after tcode starts, and kept in memory for the rest of that session rather than re-read on every turn. If you edit the file while a session is already running, that change will not be picked up until you start a new tcode session; there is currently no command to force a reload mid-session.
It does not change what still requires your approval
tcode.md is background information only, it cannot pre-approve a tool call, disable a permission prompt, or grant a tool access it would not otherwise have. Writing "always allow editing files in src/" in the file has no special effect; auto-approving a tool is still done explicitly with /config auto-approve (see Configuration), never implicitly through this file.
What not to put in it
Since tcode.md is an ordinary file in your project, likely committed to the same repository everyone on the team can see, it should be treated like any other source file for what belongs in it: no credentials, no API keys, nothing you would not otherwise commit to version control. It is meant for context about the project, not a place to store secrets tAI needs.
If a monorepo has genuinely different conventions in different subprojects, a tcode.md can be placed in each subproject's own root instead of a single one at the top level; tCode uses whichever one it finds first walking upward from where it was started, so the file closest to your working directory takes precedence over one further up the tree.
There is nothing to install or enable to use this: the file is picked up automatically purely by existing at the right filename in the right place. Deleting it, or renaming it to anything other than exactly tcode.md, simply means tCode goes back to working from the conversation alone, the same as any project that never had one in the first place.