Start here

Your first session

You've installed FreeCoder and run freecoder inside a project. Here's what a real session looks like from start to finish — so you know exactly what to expect the first time.

1. Describe the outcome

Tell FreeCoder what you want in plain language. Be about as specific as you'd be with a teammate — the goal matters more than the exact steps:

Add a /health endpoint that returns 200 OK and the app version, and write a test for it.

The agent reads the relevant files, figures out your stack and conventions, and gets to work. You don't need to point it at specific files — it finds them.

2. Watch it plan

For anything beyond a trivial change, FreeCoder lays out a short plan first — which files it intends to touch and the approach — and waits. You can approve it, comment on a step, or rewrite it before a single line changes. This is plan mode, and it's the difference between a chatbot that guesses and an agent you can trust with real work.

3. Review the edits

FreeCoder makes edits across multiple files and shows each one as a clear diff — additions in green, removals in red. Nothing is hidden and nothing is applied behind your back. If an edit isn't what you wanted, reject it or ask for a different approach in plain language.

4. Approve commands (permissions)

When the agent needs to run something — install a dependency, run your test suite, start a build — it asks first. You stay in control through permissions:

  • Approve once — run just this command.
  • Approve for the session — stop asking for this kind of command while you work.
  • Deny — don't run it; the agent adapts.
freecoder › running: npm test
  ✓ 14 passing
✓ /health endpoint added · test green

5. Iterate and ship

Keep the conversation going — “now add caching”, “handle the error case”, “commit this with a clear message”. FreeCoder works with git directly, so it can create branches, commit, and use worktrees for parallel work. Because the model is free and unlimited, you can iterate as many times as it takes.

Tips for great sessions

  • Set house rules once. Put your conventions, key commands, and do's-and-don'ts in an AGENTS.md file — FreeCoder reads it automatically every session.
  • Plan the big stuff. Use plan mode for anything spanning more than a couple of files.
  • Let it parallelize. For large jobs, FreeCoder fans work out to subagents that run at the same time.
  • Tell it how to test. If it knows your test command, it will run it and keep fixing until the suite is green.

Ready to go faster? Read Vibe coding with FreeCoder →