Tutorial: Agent Collaboration

Flint works well with AI agents because it gives them a bounded workspace, a clear entrypoint, and a durable place to put results. Just as important, it gives them shards: cognitive programs they can execute inside that workspace. This tutorial shows a practical way to use the agent features without turning the workspace into a transcript graveyard.

The Goal

By the end of this guide, you should have a workflow where:

• the agent starts with enough context to be useful
• the work stays grounded in real source material
• session state is inspectable
• durable outcomes end up back in Mesh/

The deeper goal is to let the agent run structured shard-based workflows inside Flint instead of improvising everything ad hoc.

Step 1: Prepare the Workspace Before Starting the Agent

The quality of agent collaboration is usually decided before the session starts.

Make sure the workspace has:

• a useful Mesh/(System) Flint Init.md
• the relevant shards declared and synced
• fulfilled codebase references if the work touches actual software
• a reasonably clear place for the result to land in Mesh/

Agents do much better when the workspace already has structure. Flint gives them a map, and shards give them the cognitive programs to run against that map.

Step 2: Start a Headless Session

For a background Claude session:

flint agent claude "Audit the reference codebase and update the architecture notes."

Useful options:

flint agent claude "..." --title "Architecture audit"
flint agent claude "..." --continues <session-id>
flint agent claude "..." --resume <session-id>
flint agent claude "..." --max-turns 20

The CLI creates a Flint session record, adds a run, and launches Claude in the background.

Step 3: Watch What the Agent Is Doing

To see the session list:

flint agent list
flint agent list --all
flint agent list --interactive

To stream one transcript:

flint agent watch <session-id>

This is useful because Flint does not treat agent work as magical background behavior. It treats it as inspectable workspace state.

Session files live in:

.flint/sessions/*.json

Step 4: Inspect and Control One Session

To inspect a session in detail:

flint agent session <session-id>

The session command gives you access to:

• status
• title
• description
• runs
• questions
• results
• tracked artifacts
• interface state

That makes it the main control surface once a session is in motion.

Step 5: Handle Questions Cleanly

The agent interface subcommands support structured human input.

Examples:

flint agent interface --session <id> ask "Which branch should I analyze?"
flint agent interface --session <id> request "Need decision on export scope"
flint agent interface --session <id> set repo "payments-api"
flint agent interface --session <id> get repo

The difference between ask and request matters:

• ask blocks and waits for a response
• request posts a deferred question and exits

This is much cleaner than treating every interruption as an ad hoc chat exchange.

Step 6: Keep the Agent Grounded in Source

A good Flint-agent loop usually looks like this:

1. declare or fulfill the needed codebase references
2. point the agent at the init note and relevant shard init files
3. have it inspect the actual code or source materials
4. direct the durable result back into Mesh/

That last step is critical. The transcript is not the product. The updated note, plan, report, or guide is the product. Flint is where the cognitive program runs; Mesh is where its durable output lands.

Step 7: Use the Agent for Bounded Tasks

Flint works best when agent tasks are concrete and scoped.

Good examples:

• update docs from source
• summarize a subsystem
• draft a note from a code audit
• continue a prior investigation
• answer a targeted research question

Less effective tasks are the vague ones that ask the agent to “figure out everything” with no clear workspace landing zone.

Step 8: Optional Server and Runtime Layer

If you want server-backed sessions or runtime automation, start them explicitly:

flint server start
flint runtime start

That is optional. The agent command group itself is already a usable workflow without the runtime/server layer.

A Strong Collaboration Pattern

The best Flint-agent collaboration pattern is simple:

1. prepare the workspace
2. run the agent on a bounded task
3. inspect the session
4. review the result
5. keep the durable outcome in Mesh/

When you do that consistently, the workspace stays clean and the agent becomes much more useful over time.