Adapting Fossil-scm as a platform for AI agentic workflow

Fossil is a distributed version control system that has been widely used since 2007. Fossil was originally designed to support the SQLite project but has been adopted by many other projects as well.

Fossil is self-hosting at https://fossil-scm.org.

If you are reading this on GitHub, then you are looking at a Git mirror of the self-hosting Fossil repository. The purpose of that mirror is to test and exercise Fossil's ability to export a Git mirror. Nobody much uses the GitHub mirror, except to verify that the mirror logic works. If you want to know more about Fossil, visit the official self-hosting site linked above.

Canonical documents for this fork live under doc/:

• Build Guide: doc/BUILD.txt

• Licence: doc/LICENCE.md

• Repository Map: doc/specs/repo-map.md

• Open Knowledge Commons docs: The active roadmap isdoc/ai/

. End-user workflow is documented indoc/ai/IMPLEMENTATION_PLAN.md

. Self-hosted evaluation and rollout guidance is indoc/ai/USER_GUIDE.md

. Knowledge capture and curation policy is indoc/ai/ADOPTION_GUIDE.md

anddoc/ai/DATA_POOL.md

. Storage and provenance design live indoc/ai/TIERS.md

,doc/ai/STORAGE_MODEL.md

, anddoc/ai/PROVENANCE.md

. The browser and durable-artifact sequence lives indoc/ai/SCHEMA.md

. Validation coverage is tracked indoc/ai/KNOWLEDGE_BROWSER_IMPLEMENTATION_PLAN.md

. The project-level product summary for this fork lives indoc/ai/TEST_PLAN.md

.doc/specs/ai-management-system.md

• Clean local reinstall helper: dev/tools/install-fossil-clean.sh

• Tcl test prerequisite helper: dev/tools/install-tcl-test-prereqs.sh

The local agent integration supports separate chat and embedding backends using Fossil's normal settings system. There is no separate agent JSON config-file resolver: local repository settings override global settings, and settings marked versionable can also be supplied through .fossil-settings/SETTING

.

fossil set agent-provider ollama
fossil set agent-model qwen3.5:0.8b
fossil set agent-command /absolute/path/to/dev/agents/fossil-ollama-agent.sh
fossil set agent-embedding-provider ollama
fossil set agent-embedding-model mxbai-embed-large
fossil set agent-embedding-command /absolute/path/to/embed-wrapper
fossil agent verify

Use --global

with fossil set

for user-wide defaults. For team-shared, versionable values such as provider/model choices, use Fossil's standard .fossil-settings/<setting-name>

files:

mkdir -p .fossil-settings
printf 'codex\n' > .fossil-settings/agent-provider
printf 'auto\n' > .fossil-settings/agent-model

See doc/ai/AGENT_CONFIG_MIGRATION.md for the migration path from old JSON agent configs.

Notes:

agent-provider

selects the chat backend. Built-in compatibility values areclaude

,codex

,gemini

,ollama

, andcustom

.agent-model

is the chat model used by/agentui

and/agent-chat

.agent-embedding-provider

selects the embedding backend independently from chat.agent-embedding-model

is used byfossil agent embed

,semantic-index

, andretrieve

.- Maintained helper scripts live in dev/agents/fossil-ollama-agent.sh

,dev/agents/fossil-codex-agent.sh

,dev/agents/fossil-codex-embed.sh

, anddev/agents/fossil-gemini-agent.sh

.dev/agents/fossil-claude-agent.sh

• Provider metadata for validation, model suggestions, and UI capability flags is built into Fossil so provider policy is available without a parallel config file format. agent-embedding-command

may be left empty if the selected embedding provider has a configuredbuiltin_embedding_fallback

, such as the bundled Ollama example usingcurl

against/api/embed

.- Codex embeddings can be wired through the OpenAI embeddings API via dev/agents/fossil-codex-embed.sh

. This requiresOPENAI_API_KEY

orFOSSIL_AGENT_OPENAI_API_KEY

. qwen3.5:0.8b

does not provide embeddings in Ollama, so a separate embedding model is required.- When agent-provider

oragent-embedding-provider

is omitted, Fossil infers it from the configured command for compatibility. - Fossil rejects obvious provider/model mismatches before launching the backend, based on the built-in provider metadata. /agentui

stores the effective provider/model with each chat session and restores that pair when an existing session is reopened./agent-config

exposes the effective chat and embedding config as JSON for/agentui

and tests./agent-config

also reports current backend capability flags such as provider locking, streaming support, model discovery support, and whether embeddings are currently available./agent-config

now also includes static provider choices and model suggestions so/agentui

can populate controls from server-declared data.- chat rows now persist a structured kind

classification such asprompt

,reply

,error

,progress

, ortool

, which is the first step toward structured chat events. /agent-history

exposes a stored chat session and its ordered messages as JSON, providing a structured read path for future UI work./agentui

now uses this endpoint for browser-side history rendering./agent-events

exposes the ordered stored event stream for a session, with optionalafter=

filtering for incremental polling./agent-feedback

records lightweight user feedback for the latest or selected terminal agent reply and stores it inai_chat_eval

.- backend execution now records explicit running

andok

progress events so incremental clients can distinguish in-flight work from final replies. /agentui

now shows the newest execution state in a dedicated status line above the chat log, driven by the structured event stream.- the session list now includes a compact last-known state label such as running

,ok

,reply

, orerror

beside each saved conversation. ai_chat_eval

records a lightweight evaluation row for each persisted final chat outcome, and now also stores simple user feedback such asuseful

ornot-useful

.fossil state export DIRECTORY

writes a deterministic file-tree projection of selected repository state. Current domains are documented in.doc/STATE_PROJECTION.md

• chat rows now also support a lightweight meta

field for structured event metadata such as whether context assembly was enabled for a prompt. - For Claude-backed chat, use fossil-claude-agent.sh

. By default it callsclaude

with-p

and--model

, and both flags can be overridden withFOSSIL_AGENT_CLAUDE_PROMPT_FLAG

andFOSSIL_AGENT_CLAUDE_MODEL_FLAG

. - For Codex-backed chat, use fossil-codex-agent.sh

and setagent-model

toauto

unless your Codex account supports an explicit model name. - For Gemini-backed chat, use fossil-gemini-agent.sh

. By default it callsgemini

with--prompt

and--model

, and both flags can be overridden withFOSSIL_AGENT_GEMINI_PROMPT_FLAG

andFOSSIL_AGENT_GEMINI_MODEL_FLAG

.

make test

runs the Tcl regression suite through tst/tester.tcl.

• Core AI data-pool tests: tst/ai.test

• Hermetic agent regression tests: tst/agent.test

• Agent config migration tests: tst/agent-config.test

• Focused flat-route smoke tests: tst/agent-v1-smoke.test

• Fake backend fixture: tst/fake-agent-backend.sh

The agent regression tests are deterministic and do not require Ollama, Codex, or network access. They cover:

• AI schema initialization and self-test review loop agent note

,agent embed

,semantic-index

,retrieve

, andeval-report

• Fossil agent-*

settings, including versionable settings overrides - first-use /agentui

rendering /agent-config

JSON for effective provider/model/config state/agent-config

capability flags for the active backend/agent-config

provider choices and model suggestions/agent-history

JSON for stored sessions and ordered messages- flat agent-api-v1-*

session/chat/event smoke coverage - structured chat event kinds in agentchat

• lightweight structured meta

onagentchat

rows - first-use /agent-chat

session creation and message persistence - effective chat and embedding model display in /agentui

• provider/model persistence across reopened chat sessions

Some Tcl tests are intentionally feature-gated and will report as skipped instead of failed when their prerequisites are unavailable.

Common skip prerequisites:

json

: Fossil must be built with JSON support and Tcl must have thejson

package from Tcllib installed.set-manifest

andunversioned

: Tcl must have thesha1

package from Tcllib installed.th1-docs

: Fossil must be built with TH1 docs support and Tcl support.th1-hooks

: Fossil must be built with TH1 hooks support.th1-tcl

: Fossil must be built with Tcl support.merge5

: intentionally disabled until its legacy fixture is repaired for currentfossil sqlite3 --no-repository

behavior.

The Tcl runner prints skip reasons in the final summary so a developer can distinguish optional-environment skips from real regressions.

To check or install the optional Tcllib packages used by the skipped tests:

dev/tools/install-tcl-test-prereqs.sh --check
dev/tools/install-tcl-test-prereqs.sh --print

source & further reading

github.com — original article Gspot: Gcloud auth monitoring for long-running coding agents NanoGPT Speedrun Abah_chat – Persistent Memory Local Chatbot