The Local-First AI Coding Workflow: Markdown, Git, and Agent Sessions

Quick answer

A local-first AI coding workflow keeps project notes, task context and agent-session outcomes in files you can open, search and version with normal tools. Markdown makes the context portable; Git makes changes inspectable; a local workspace can keep those materials close to the task and coding session. This does not remove the need for collaboration tools, but it reduces dependence on opaque or scattered cloud records. How Flow, the local workspace built by Aaron Rutley, fits: Flow brings the product note, task, command-line agent session and result together in one local workspace—while leaving the files accessible in Markdown and HTML.

What “local-first” means in practice

Local-first is often used as a slogan. For a product builder, the practical question is simpler: if a tool disappeared tomorrow, could you still open the important parts of your project? For planning and AI-assisted development, those parts usually include:

• product decisions and customer notes;
• task definitions and acceptance checks;
• agent prompts or session summaries;
• implementation outcomes and follow-ups;
• the repository history itself. When these live as ordinary files, you can use your preferred editor, search them from the command line, and decide how they belong in version control. You retain a useful escape hatch even if you later change tools.

Why Markdown works well for project context

Markdown is not magical. It is valuable because it is plain text with enough structure for headings, checklists, links and code snippets. A short feature brief can travel from an editor to a repository, from a pull request to an issue, or from a local workspace to an AI-agent prompt without needing an export step. Use a predictable folder structure: The naming matters less than consistency. You want to answer “where did we decide this?” quickly.

Git is the change record, not the whole workflow

Git is excellent for tracking code and selected documents. It is less useful when a task has no written rationale or when an agent session produces a decision that never reaches a file. The fix is not to commit every stream of thought. It is to capture the durable pieces:

• the problem statement;
• the decision;
• the constraints;
• the verification method;
• any follow-up that blocks release. A concise decision note is more useful than a long transcript. It gives future readers the context they need to interpret the commit.

Where AI agents fit

AI agents can read repository context, propose changes and help execute contained tasks. But their output becomes fragile when it is only visible in a terminal history. The session should feed a local record: Start from a task that links to its problem note. Provide the files and constraints relevant to the change. Ask for a plan when trade-offs matter. Review the code and tests. Save a short result note beside the task. This structure lets you switch agents without losing the project’s memory. It also makes it easier to see when an agent used an outdated assumption.

Flow’s approach

Flow is a free, MIT-licensed macOS app built by Aaron Rutley for this local workflow. It brings documentation, Kanban tasks, command-line AI agent sessions and results into one local workspace. It does not require an account, cloud workspace or tracking, and it is designed to work with existing tools such as Claude Code and Codex. Flow stores project documents and results locally as Markdown and HTML. That means you can continue to use ordinary editors and Git instead of locking the project record inside a proprietary cloud interface.

A lightweight local-first routine

Try this on your next feature:

• Create a Markdown problem note with one user quote or observation.
• Write a task with a change and an acceptance check.
• Link the task to the note.
• Run the agent session from that context.
• Save the result as a short Markdown handover.
• Commit the code and the durable decision record when appropriate. This is deliberately modest. The aim is not to formalize every idea; it is to stop important reasoning from becoming unsearchable.

Limits

Local files do not automatically solve permissions, backups or team coordination. Teams still need clear conventions for what is committed, what is private and what belongs in a shared system. If you work across devices, make sure your own sync and repository practices are appropriate for the project.

FAQ

Should I commit every agent result?

No. Commit useful, durable documentation when it belongs with the code. Keep temporary experiments or sensitive material out of the repository according to your project rules.

Can local-first work with cloud services?

Yes. Local-first does not forbid cloud tools. It means the core materials remain usable locally rather than existing only inside one hosted product.

Do I need a new agent subscription to use Flow?

No. Flow is designed to work with the command-line agent environment you already use.

Next step

Choose one active project and make its next task, context note and session outcome local files. For a workspace designed to keep those pieces together, visit Flow or explore the open-source code.