# Managing context

A chat’s context window holds Flockbay’s instructions and tools, then the messages, tool results and pictures in the chat, which go with each request. A game outlives any one chat: keep its plan and conventions in project files, give each task its own chat, and compact between tasks.

Source: https://flockbay.com/docs/managing-context/ · Updated 2026-10-31

## What a chat’s context holds

Every request a chat makes carries Flockbay’s instructions and tool definitions, then the conversation so far: your messages and attachments, the agent’s replies, every tool result and every picture. On Flockbay’s hosted models and on ChatGPT the chat is a Codex thread; on Claude Code it is Claude Code’s own session, resumed for each message. Either way the history goes with each request; on Flockbay’s hosted models, older pictures and long earlier tool results are shortened first, as described below.

So the same ask costs more late in a long chat than early in a new one. On hosted models it draws more of your usage, and on your own Claude or ChatGPT it reaches your plan’s limits sooner. A long history also gives the model more to sort through, and what was said early on gets less of its attention.

| In the context | When it is added | How to keep it small |
| --- | --- | --- |
| Flockbay’s instructions and tools | Every request, the same in a new chat | Nothing to do. Flockbay’s guides load only when the agent reads one. |
| Your messages and attachments | Each message | Attach the file or picture the change is about, not every one you have. |
| Tool results | Each step: scene trees, scripts, output, diffs | Name the node, script or file, so the agent reads that and not the project. |
| Pictures | Each viewport capture the agent takes | Ask for a region, or for the value instead of a picture. |

## A routine for a long project

1. Keep the plan in **GAME-BRIEF.md** and your conventions in **AGENTS.md**, at the game’s root. Every chat can read them, and no chat remembers another.
2. Give each feature, bug or system its own chat: **New chat** (Ctrl+N), renamed after what it is for (F2 in Chats).
3. Name the node, script or file in each ask.
4. When the feature plays right, commit it, and ask Flockbay to note in the project what it did and what comes next.
5. Start the next task in a new chat that opens on those notes, or compact this one if the next task builds on it.
6. Watch the context ring. When it turns yellow, compact at the next break rather than in the middle of a fix.

## The context ring

The ring first in the composer’s meters shows how full this chat’s context window is, as "41%", or as the ring alone where the composer is narrow. Its tooltip has the tokens, "Context: 41% used · 82K of 200K tokens", and pressing it opens a bar and **Compact chat**. When the engine has not said how large its window is, it shows the tokens alone.

It reads what Claude Code or Codex reported for the chat’s last turn, so it appears after a chat’s first turn and moves when a turn ends, not while one runs. From 90% the ring and its bar turn yellow: the engine compacts on its own soon after, or the next turn may not fit.

The usage meter beside it is a different measure: how much of your usage, or of your own plan’s limits, is left across every chat.

## Compact a chat

Type **/compact**, or press **Compact chat** in the ring’s menu. Your next message then starts by summarizing the chat so far, and the turn carries on from that summary instead of the full history. On Flockbay’s hosted models and ChatGPT, Codex writes the summary; on Claude Code, Claude Code runs its own /compact.

Each engine also compacts on its own as the window fills, and on Flockbay’s hosted models and ChatGPT, Flockbay compacts a chat before a turn once its history grows too large to send. When a chat fills its window anyway, the turn stops with **Context window full** and **Compact and continue**, which compacts the chat and sends your message again.

A summary keeps the gist and drops detail: an exact error line, a value you settled on, why a fix was turned down. Write what must survive into a file first, and compact between tasks, when the summary has least to lose. Compacting reads the whole chat once more, so when the next task has nothing to do with this one, a new chat costs less.

## Start a new chat for a new task

**New chat** (Ctrl+N) starts a chat with an empty conversation. It knows the game from its files, GAME-BRIEF.md and AGENTS.md included, and nothing from other chats, so it carries none of the last task’s dead ends.

A game can have several chats. Ctrl+Tab steps between them, and Ctrl+click on a chat in Chats opens it beside this one. **Ask** (Ctrl+Shift+A) reads and plans without changing a file, so one chat can work out a plan while another builds.

Start a new chat when the subject changes, when two corrections in a row have not landed, or when the ring is high and the next task is unrelated. Switching a chat to another engine, from a hosted model to Claude Code for example, also starts a fresh conversation in it, because each engine keeps its own.

## Keep what matters in the project

Files are what every chat shares. In a game Flockbay creates, it writes two at the root. A project you opened from elsewhere, or a game built from a spec with no brief, may have neither; add an AGENTS.md of your own.

**GAME-BRIEF.md** is the brief, written when you approve it: the first playable, the steps after it, and what is not in this version. Flockbay reads it first on every message, and when you ask for something the brief left out, it moves that item in the file and notes the date.

**AGENTS.md** is written when Flockbay creates the game, for any coding agent that opens the folder: where the game was made and which tools run and test it. It is yours from then on. Add what an agent cannot see in the files: the folder layout, naming, which autoload owns what, collision layers, input actions, and anything not to touch. Keep it short, because every chat that reads it pays for every line. Codex reads AGENTS.md and Claude Code reads CLAUDE.md; a CLAUDE.md with the line `@AGENTS.md` makes Claude Code read the same file.

For a long project, add a notes file of your own, such as NOTES.md: what is done, what is next, and each decision with its reason. Ask Flockbay to update it when a feature lands, and open the next chat with "Read NOTES.md, then …". Commit messages keep the same record in Git; [Version control](/docs/version-control-with-git-and-github/) has the panel.

## Point the agent at the thing

An ask that names the node, script or file sends the agent straight to it. One that names nothing sends it looking, and every file and tree it reads on the way stays in the chat. **Ask Flockbay**, on a node in the Scene dock, puts the node with its scene and script into the message, and @ in the message box adds a file or asset.

Flockbay’s reading tools have limits, and you can ask for narrower reads: one branch of the scene tree rather than the whole scene, a node’s named properties rather than every Inspector property, project settings under one prefix. When a number answers the question, such as the player’s position or a timer’s time left, a read of the running game costs far less than a screenshot.

## Small scripts and scenes cost less to read

Flockbay’s script reader returns a script whole, so each time the agent reads a 2,000-line player.gd that way, all 2,000 lines go into the chat, even when the change is one line. Split it the way Godot recommends, into scenes and scripts that each do one job, such as movement, health or the inventory, and the agent reads only the part it changes.

A .tscn is text, and it holds its sub-resources and painted tile data inline, so a baked mesh, a long animation or a large TileMapLayer can make one scene file large. Save big resources as their own .tres or .res files and the scene stays small to read.

Flockbay’s project listing leaves out .godot/, .import files, add-ons unless asked, and the folders Godot skips because they hold a .gdignore file. Put source art and reference material the game does not load in such a folder, and Godot does not import it either.

## Pictures are the heaviest thing in a chat

Every viewport capture stays in the conversation and is sent again with each later request, and so is every picture you attach. A turn that takes ten screenshots to tune a jump leaves ten pictures in the chat.

Ask for a capture of the region you care about, or for the value instead of the picture. Put reference art in the project and name its path rather than pasting it into a long chat.

On Flockbay’s hosted models the newest picture always goes, and once the pictures in a chat pass a budget the oldest are left out, each with a note telling the agent so. A long result from an earlier step is shortened to a note the same way, and the agent reads it again when it needs it. On ChatGPT every picture stays until the chat is compacted, and Claude Code keeps or compacts them as it does in a terminal.

## Let helpers do the reading

Flockbay’s agents each work in a context of their own and hand back a report, so the chat gets the findings and not every step that found them. The **Playtester** plays the game in a background run and reports what a player would trip on. The **Researcher** looks up comparable games and Godot’s documentation. The **Reviewer** checks GDScript for parse errors, runtime errors and logic mistakes before you play. None of them changes a file: the chat’s own agent makes the fixes.

On Flockbay’s hosted models a helper starts only when you ask for one, as in "have the Playtester play the first level", and its work counts against that turn’s usage. On Claude Code and ChatGPT the agent may also start one on its own.

## Revert takes back files, not the conversation

**Revert this turn**, on a turn’s receipt, or /undo for the newest turn, puts back the files the turn changed, and the turn stays in the chat: the agent still remembers making the change. After a revert, say what you took back and why, or start a new chat if the whole direction was wrong.

## Your own agent over MCP

An agent you connect over MCP, such as Claude Code or Codex in a terminal, manages its context with its own commands and its own instruction file, as it does on any project. Flockbay’s server adds its tool definitions and a short set of instructions to each session; its guides and its agents’ briefs load only when your agent asks for one. With **Install skills and hooks**, Claude Code’s hooks also add a few lines: the game and its last run when a session starts, and any parse errors after a script edit. Connecting writes nothing into the game folder: the AGENTS.md there is the one written when Flockbay created the game.

Related: [Asking for a change](/docs/asking-for-a-change/), [How Flockbay’s agent works](/docs/what-director-1-does/), [Plans and usage](/docs/plans-and-usage/), [Connect your agent (MCP)](/docs/connect-your-own-agent/), [Godot: Scene organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/scene_organization.html), [Claude Code: CLAUDE.md and memory](https://code.claude.com/docs/en/memory), [Codex: AGENTS.md](https://developers.openai.com/codex/guides/agents-md)