____ ___ _
/ ___| / _ \ | |
\___ \| | | || |
___) | |_| || |___
|____/ \___/ |_____|
Sol is a coding assistant that runs entirely on your own computer. Describe a task in plain English and it goes to work: editing files, running commands, using git, and searching the web when needed. There is no plan gate and no per step approval. When you want a deliberate, multi model pass instead, an expert council is one command away.
The name comes from the Latin word for sunlight. Ollama runs open source language models locally, so once you have pulled a model, nothing you type and no file you open ever leaves your machine. It works offline, with no account and no API key.
Run sol inside a project folder. It shows the active model and waits at a task> prompt. Type something like "add input validation to the signup form" and Sol runs the whole thing in one agentic loop: the model picks a tool, Sol runs it, feeds the result back, and repeats until the task is done. You watch it happen in the terminal, with a running token count at the bottom.
Whether that loop goes straight to a single coding model, hands the task to the full council, opens a plain conversation, or gets classified automatically depends on the operating mode you have set. See Operating modes below.
Nothing destructive runs without asking first. See Safety.
Ollama runs the models on your machine. Sol talks to it in the background at localhost:11434. Python 3.10 or newer runs Sol itself.
brew install ollama
git clone https://github.com/16A9DA/sol.git
cd sol
pip install -e .On Linux or Windows, install Ollama from ollama.com instead of using brew.
Start Ollama so the models have somewhere to run.
ollama serveThen run the setup wizard, which walks you through picking and pulling starter models.
sol setupOr do it by hand. qwen2.5-coder:7b is a solid starting point for coding, and the download happens once.
sol model pull qwen2.5-coder:7bWhen it finishes, Sol asks whether to make it your default. Say yes and you are ready.
- Open a terminal and change into the project folder you want to work in.
- Start the assistant with
sol. - At the
task>prompt, type what you want in plain English, for exampleadd input validation to the signup form, and press enter. - Sol runs the task, calling tools and streaming its progress, with no approval step in between.
- When the task finishes, the prompt returns. Type the next one, or leave the session.
Want a deliberate pass first instead of the default fast path? Type plan <task>, read what the planning expert drafts, then execute to build it. See Operating modes and The expert council below.
A bare task, one typed directly at the prompt with no command in front of it, is routed according to the current mode. Four modes exist.
coding Runs once on the coding expert. The default, and the fastest path.
council Runs the full plan, architect review, code, and review pipeline, each phase on its own expert model.
conversation Goes to the conversation expert instead of a coding model. Talk only, no tools, no file edits.
auto The router reads the task, classifies it as coding, planning, or reasoning, and picks the matching expert on its own.
Set the mode from the prompt, and it persists across sessions until you change it again.
mode council
mode coding
coding suits most day to day edits. council is worth reaching for on a task where getting the design right matters more than speed. conversation is for when you want to talk something through without Sol touching any files. auto is a middle ground: you stop thinking about which mode fits and let the router decide per task.
Native model reasoning is a separate toggle, independent of operating mode.
reasoning on
reasoning off
Every kind of work has its own expert model: a fast model for ordinary coding, a reasoning model for planning, a large model for architecture review, and a separate model for reading diffs. You choose which model fills each role. Nothing expensive runs unless you ask for it.
sol config --coding qwen2.5-coder:7b
sol config --planning deepseek-r1:14b
sol config --architect qwen3-coder:30b
sol config --reviewer qwen2.5-coder:7b
sol config --conversation llama3.1:8bAny role left unset falls back to your active model, so the council works even with a single model pulled.
Drive it directly from the task> prompt instead of waiting for mode council:
plan <task> Planning expert drafts a structured plan and saves it to plan.md. No files change.
architect Architect expert reviews the saved plan for design, security, and tradeoffs.
execute Coding expert builds the saved plan.
review Reviewer expert reviews your current git diff.
team <task> Runs plan, architect, code, and review back to back, automatically.
chat <task> Talk to the conversation expert directly. No tools, no file edits.
A typical deliberate flow is plan add rate limiting to the API, a read through the plan, optionally architect, then execute. team <task> does the same four steps without stopping in between. For quick work, skip all of it and type the task directly.
Everything above runs on models pulled through Ollama, entirely on your machine. If you also want to point a role at a hosted model, for a task that needs more capacity than your hardware can run locally, Sol supports that too, without changing how you use it.
Set a role to a string of the form provider:model_id instead of a plain Ollama name.
sol config --architect nim:meta/llama-3.1-70b-instructSupported providers are nim (NVIDIA NIM), openai, and groq, plus any other host that speaks the same chat completions shape through a custom base URL. Put the matching API key in ~/.freecode/.env:
NIM_API_KEY=your-key-here
A role you never set this way keeps running against your local Ollama instance. This is entirely opt in. Leave it alone and no request ever leaves your machine.
exit Quit the assistant.
quit Same as exit.
done End the session early and print the token dashboard first.
Type any of these at the task> prompt and press enter. An empty line also exits. All three print a short goodbye and return you to your shell. Your history and settings save automatically, so the next sol picks up where you left off.
If a task is mid run and you need to stop it, press Ctrl+C to interrupt, then exit from the prompt.
Everything runs through the one sol command. No arguments starts the assistant; everything else is a subcommand. Run sol help for the full list.
sol Start the assistant. Welcome screen and task prompt.
sol help List every command.
sol setup First run wizard: pick and pull starter models.
sol model Download, list, switch, and remove local models.
sol config View and change settings.
sol history Show your past tasks.
sol clear Erase the saved session memory.
sol index Build or refresh the search index for the current project.
Managing models:
sol model pull qwen2.5-coder:7b # download a model
sol model list # show installed models, active one marked
sol model use qwen2.5-coder:7b # set the active model
sol model remove qwen2.5-coder:7b # delete a model from diskAsk to use a model you have not downloaded and Sol offers to pull it. Remove the model you were using and it tells you to pick a new one. An untagged name matches a tagged pull, so qwen2.5-coder finds qwen2.5-coder:7b.
Some commands run inside a session without ever calling a model, so they cost zero tokens: help, history, clear, index, model list (and model pull|use|remove <name>), mode, and reasoning. The council commands plan, execute, architect, review, team, and chat also run inline; see The expert council.
Switch models mid session by typing model qwen2.5-coder:7b or switch model to llama3 at the prompt. Sol changes the active model and keeps going, which is handy for comparing how two models handle the same task.
Type / at the task prompt to open a menu and pick a command with the arrow keys, or type the name yourself. These do the same thing as the plain text shortcuts above and run inline for zero tokens.
/model Download, list, switch, and remove local models. Args: list|pull|use|remove <name>
/config View or change settings. Args: --model, --coding, --planning, --architect, --reviewer, --reasoning, --conversation, --temperature, --context
/history Show past tasks and token usage.
/clear Erase the saved session memory. Args: --history
/index Build or refresh the search index for the current project.
/mode Pick how a bare task is routed. Args: coding|council|conversation|auto
/reasoning Toggle native model reasoning. Args: on|off
/plan Planning expert drafts a plan. Args: <task>
/architect Architect expert reviews the saved plan.
/execute Coding expert builds the saved plan.
/review Reviewer expert reviews the working tree diff.
/team Runs plan, architect, code, and review automatically. Args: <task>
/chat Talk to the conversation expert directly. Args: <task>
/done End the session early and show the token dashboard.
Your global skills also appear in the menu by name, so you can pull one in directly.
Type @ and Sol suggests files and folders from your project root, narrowing as you keep typing and descending into folders like a modern editor. A live dropdown also appears after mode (the four modes), reasoning (on or off), model , and switch model to (your pulled models). Suggestions from past prompts appear inline as you type; press shift+tab to accept one.
Prompts that ask you to choose use arrow keys rather than typed answers: yes or no confirmations, model pick lists, and the like all take left, right, up, down, then enter. A confirmation on a repeating action also offers "allow all this session," so you are not asked again for that kind of action.
While working, Sol reaches for tools on its own. You never call these directly; the model picks the right one for each step.
file Read, write, create, delete, and search inside files.
shell Run terminal commands.
git Check status, view diffs, stage, commit, push, and read the log.
web Search the web through DuckDuckGo. No account or API key needed.
browser Open a web page and pull out its main text.
Long running commands such as dev servers start in the background so they do not block the loop. When Sol writes over an existing file, it shows a side by side diff first.
Sol stops and asks before anything it cannot easily undo. It will not delete a file, overwrite an existing one, or run a dangerous shell command such as rm, dd, mkfs, or drop table until you confirm. Commits happen on their own, but git push always asks first and shows the remote and branch it is about to push to. Sol can move fast, but it will not surprise you with a change you did not agree to.
Mention a file or folder with an @ followed by a relative path.
fix the bug in @./src/models/user.py
use the schema from @../otherproject/schema.py
For a file, Sol reads it and includes a summary. For a folder, it includes the file tree so the model knows what is there.
Skills are written instructions that shape how Sol behaves, and come in two kinds.
Project skills live in a file named .freeai in your project root, one rule per line.
always use type hints
never modify files in the migrations folder
prefer async functions
Sol looks for this file starting from your current folder and walking upward. Whatever it finds gets added to every request in that project, automatically.
Global skills apply across every project. Each one is a folder under ~/.freecode/skills/ containing a file named SKILL.md, whose first paragraph is a short description. Sol reads only these descriptions to decide which skills fit the current task, then loads the full text of whatever matches. On first run it creates the skills folder with two starter skills, general-coding and ponytail.
A skill file looks like this:
~/.freecode/skills/django-rest/SKILL.md
Skill for building Django REST Framework APIs. Covers serializers,
viewsets, and permissions.
Rules:
- Use ModelSerializer unless a field needs custom logic.
- Put business logic in services, not views.
- Always paginate list endpoints.
Keep that first paragraph specific, since it is the only part Sol reads when deciding whether a skill applies. When a skill is in use, Sol prints its name so you can see what is shaping its behavior.
Three behaviors are always on, built into the prompt the agent works from, and kept as separate documented rulesets in freecode/core/defaults.py, each borrowed from an upstream project so you can read the original.
Headroom governs how the agent handles tool output. A long result from a command or file read gets shortened before the model sees it, with the full text kept under a short reference id. If the model needs the part that was cut, it asks for the original by that id, which keeps the model's limited context on what matters.
Caveman governs how the agent writes: terse replies with filler and hedging dropped, while code, file paths, command names, and error messages stay exact. Anything where brevity would cause confusion, such as a security warning, gets written out in full regardless.
Ponytail governs how much code the agent writes. Before writing anything, it climbs a ladder looking for the smallest solution that works: reusing code already in the project, reaching for the standard library, or writing one line instead of fifty. It never cuts input validation, error handling, or security checks to save space.
How closely a model follows caveman and ponytail depends on the model itself; smaller local models follow layered instructions less reliably than larger ones. Headroom's compression is handled by Sol directly and behaves the same regardless of which model is active.
caveman https://github.com/JuliusBrussee/caveman
ponytail https://github.com/DietrichGebert/ponytail
On a large project, mentioning every relevant file by hand gets tedious. Sol can build a searchable index of your code so it finds the right files on its own.
The index builds in the background on startup by default, with no prompt. Sol reads your files, splits them into chunks, and stores a fingerprint of each chunk on disk. From then on, before each task, it searches that index for the parts of your code most related to what you asked, includes them automatically, and prints which files it pulled in. If the embedding model is not installed, indexing stays off and @ mentions still work on their own.
This feature needs a second, smaller model that turns text into those fingerprints, downloaded once:
sol model pull nomic-embed-textBuild or refresh the index yourself at any time:
sol indexThe index tracks the files git tracks, skips anything that is not text, and only re reads files that changed since last time. Like everything else, it stays on your machine.
Sol keeps its settings in ~/.freecode/config.json: your active model, your council roles, your operating mode, and other preferences. View and change them with sol config.
sol config # show current settings
sol config --model qwen2.5-coder:7b # set the active model
sol config --coding qwen2.5-coder:7b # set the coding role
sol config --planning deepseek-r1:14b # set the planning role
sol config --architect qwen3-coder:30b # set the architect role
sol config --reviewer qwen2.5-coder:7b # set the reviewer role
sol config --reasoning deepseek-r1:14b # set the reasoning role
sol config --conversation llama3.1:8b # set the conversation role
sol config --temperature 0.2 # change how adventurous the model is
sol config --context 8192 # change the context window size
sol config --reset-prompts # re-enable remembered setup promptsSol adjusts to your terminal width. On a narrow window it drops columns from the token dashboard and model list and shortens the bottom status bar, so output stays readable instead of wrapping into a mess.
While a task runs, a spinner shows the current phase and a live counter tracks tokens used. At the end of a session, a table breaks down where those tokens went and flags the step that cost the most.
Sol runs locally from start to finish by default. Models run inside Ollama on your own computer at localhost:11434, the search index sits in your home folder, and your code, tasks, and queries stay on your machine. The only things that leave it are the initial model downloads, any web searches you explicitly ask for, and requests to a remote provider you have deliberately configured for a specific role.