What is cognitive-substrate?

Cognitive Substrate is a local task runner that uses an AI model, Google Gemini, to work through goals you give it. You are not chatting with a bot here. Instead you write down a goal in a plain text file, and the system breaks that goal into a queue of smaller tasks, then works through them one at a time using an AI agent that can read and write files and run shell commands, but only inside its own workspace folder. Everything the system knows or has done lives as ordinary files you can open and edit yourself: the goal, the task list, a knowledge file, a dashboard, and a folder of evidence from past runs. Nothing is marked complete until it passes checks, and often a second, more skeptical AI review as well. The project also keeps a separate memory of immediate context versus longer term lessons learned, adding one distilled lesson after each run. The system can run multiple separate workspaces at the same time without blocking each other, and it can run continuously as a background process. It supports custom skill files that get offered to the agent when relevant. There is an evaluation harness for testing how well the system performs, a self improvement loop that turns failures into concrete proposed fixes, and governance features like spending budgets and an approval step that blocks dangerous commands when running autonomously. For safety, native shell commands are not treated as fully isolated. There is an optional container mode that runs commands inside Docker for real isolation, and a separate sandbox for running JavaScript snippets safely without Docker. The project is honest that without the container mode, a native shell can still reach outside the workspace, so it advises against running untrusted prompts on a machine you care about. You can also interact with the system through a few different interfaces: a command line tool, a terminal based visual interface, and a web dashboard, all sharing the same underlying data. Getting started requires Node.js version 18 or newer, and a Gemini API key is optional, since the system can run in a simulation mode without one. The project is released under the MIT license.