Deep Dive into the flow-coder Agent: Optimizing Code Generation with Intelligent Context

The flow-coder is a powerful code agent designed to assist in software development by leveraging the power of different AI models. To ensure the agent's success and efficiency in your projects, it is fundamental to understand how it manages context, selects files, and utilizes specific models for each step.

Understanding the Context Window and Its Importance

The context window refers to the amount of information that an AI model can "see" and process at a given moment. For a code agent, this is crucial: a larger context allows the model to better understand the project, dependencies, and the purpose of the code it is generating or modifying. However, models with very large context windows can be slower or more expensive.

flow-coder addresses this with a smart strategy, separating the responsibilities of context selection and code generation, using models optimized for each task.

flow-coder Configuration

The agent's configuration is done through the coder.yml file, which allows adjusting the agent's behavior to meet your project's needs:

coder:
  persona: The persona description for the AI assistant.
  model: The AI model for code generation and assistance.
  context:
    mode: The level of detail for file contents.
    scope: The scope of files to include.
    selection:
      model: Model used to select files for context.
      step: Step for new file selection in each session run.
      limit: Limit for the number of selected files.

Let's detail each aspect:

1. AI Models and Their Applications

flow-coder allows the selection of different AI models, each with its characteristics and optimizations. It is crucial to understand which model is most suitable for each function:

Category	Model	Context Window	Observations
Context Selection	`flow-bedrock-nova-lite`	1 million tokens	Highly recommended for file selection. Excellent for "reading" large repositories and identifying the most relevant files, as it prioritizes a giant context window over code generation capability.
	`flow-gemini-2.5-pro`	1 million tokens	Great for selection, but may show errors in `max_tokens` calculation in some scenarios. It is also a good option for code generation.
	`flow-gemini-2.0-flash`	1 million tokens	Similar to Gemini 2.5 Pro, with a large context window, but may also have errors in `max_tokens` calculation.
Code Generation	`flow-bedrock-claude-37-sonnet`	-	High-performance model for code generation and refactoring. Focused on the quality and precision of the generated code.
	`flow-gemini-2.5-pro`	1 million tokens	A versatile model that can be used for both context selection and code generation, offering a good balance.
Other Models	`flow-openai-gpt-4o`	-	Robust model with good capability for various tasks, including code.
	`flow-openai-gpt-4o-mini`	-	Lighter version of GPT-4o, can be useful for less complex tasks.
	`flow-bedrock-nova-lite`	1 million tokens	Although excellent for selection, its focus is not on high-quality code generation.
	`flow-foundry-deepseek-r1`	-	Another model option for experimentation, with specific characteristics from its developer.

Essential Optimization Tips:

Intelligent model selection: For **selection.model**, prioritize models with large context windows, such as flow-bedrock-nova-lite, flow-gemini-2.5-pro, or flow-gemini-2.0-flash. They are excellent at "reading" large codebases and identifying the most relevant files.
For the **model** (the model that actually generates the code), choose those optimized for this task, such as flow-bedrock-claude-37-sonnet or flow-gemini-2.5-pro.
Test and Experiment: Remember the importance of testing different models for each situation. Ideal performance may vary depending on the project type, programming language, and task complexity.

2. Context Management (`context.mode` and `context.scope`)

flow-coder offers different strategies for including file content in the model's context:

context.mode: Defines the level of detail for file content:
- full: Includes complete file content. Ideal for high precision, but consumes more tokens.
- compact: Includes a shrunk version of the file content (experimental). Useful for larger projects where full would exceed the context window.
context.scope: Defines the scope of files to include:
- all: Includes all files in the project.
  - full/all: This combination is recommended only for smaller repositories, as it sends the complete content of all files. It supports approximately \~10,000 lines of code on models like GPT-4o. If the project is larger, this option will likely exceed the generation model's context window.
- selected: Includes only selected files.

3. File Selection (`context.selection`)

For larger projects, intelligent file selection is vital to keep the context manageable. flow-coder allows you to configure how this selection is made:

selection.model: Defines the AI model used to select the most relevant files. As mentioned, models with large context windows (e.g., flow-bedrock-nova-lite) are ideal here, as their main function is to map the project.
selection.step: Controls the frequency of new file selection in each session run.
selection.limit: Sets the maximum number of selected files. This is a crucial configuration for large projects, as it prevents the context from becoming excessive, even after the initial selection.

Ignoring Files with `.coderignore`

To further refine the context, flow-coder respects a .coderignore file. This file works exactly like a .gitignore, allowing you to specify patterns for files and directories that should be ignored by the agent when building the overall context.

Benefit: By ignoring irrelevant files (such as node_modules/, build files, logs, etc.), you ensure that the model's context is focused on essential source code, optimizing context window usage and improving the relevance of the agent's responses.

Ideal Workflow with flow-coder: Iteration and Continuous Commit

To maximize code efficiency and quality with flow-coder, we recommend an iterative and incremental workflow, focused on concise commits and continuous review. This method not only optimizes interaction with the AI agent but also improves the traceability and maintainability of your commit history.

Step-by-Step Workflow

Choose a Small Task Increment: Start by breaking down your larger task into small, manageable increments. Each increment should focus on a single objective, enough to be represented by a concise commit. Think of something that would only take a few minutes to code manually.
Create a Specific Prompt for the Increment: Craft a clear and objective prompt for flow-coder, describing exactly what you want it to do for that small increment. Be as specific as possible to guide the AI.
- Example: Instead of "Improve my code," use "Add a calculate_media(list) function that returns the average of the elements in a list, handling non-numeric values."
Run the Prompt in flow-coder with --apply: Execute the coder run command with the --apply flag. This will make flow-coder not only generate the code but also apply the changes directly to your files.
```
coder run "Your prompt here" --apply
```
Important: Do this only after committing the previous change (if any). flow-coder works with the current state of your repository.
Review Changes in your IDE: Immediately after flow-coder applies the changes, carefully review them in your preferred IDE. Use the IDE's side-by-side diff viewer to compare the generated code with the previous state. Check the logic, syntax, coding styles, and adherence to requirements.
Make the Commit: After reviewing and validating the generated code, make a concise commit that reflects only the changes introduced by that increment and by flow-coder. Use a clear commit message that describes the added or altered functionality.
```
git add .
git commit -m "feat: Adds average calculation function"
```
Repeat the Cycle: With the commit made, you have a clean new starting point. Repeat the cycle (choose the next increment, create the prompt, run flow-coder, review, and commit) until the main task is complete.
Create the Pull Request (PR): Once all commits for the main task have been made, create your Pull Request. With this flow, your PR will have a clean commit history, easy to review, and with each change well-defined.

Gotchas and How to Avoid Them

A crucial point to keep in mind when using flow-coder, especially with --apply, is session management:

Manual Changes and coder reset: If you need to make manual changes to the code generated by flow-coder (e.g., correcting something it didn't understand perfectly), and you decide to run coder run --apply again in the same session for a new suggestion, your manual changes will be discarded.
Solution: If you've made manual changes and want flow-coder to take them into account for the next iteration, you must reset the flow-coder session with coder reset before running coder run again. This ensures it starts with a clean state, reading the changes you've made to your file system.