# Adapting Fossil-scm as a platform for AI agentic workflow

> Source: <https://github.com/BenSiv/fossil-scm>
> Published: 2026-08-23 00:36:50+00:00

Fossil is a distributed version control system that has been widely
used since 2007. Fossil was originally designed to support the
[SQLite](https://sqlite.org) project but has been adopted by many other
projects as well.

Fossil is self-hosting at [https://fossil-scm.org](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/](/BenSiv/fossil-scm/blob/master/doc):

- Build Guide:
`doc/BUILD.txt`

- Licence:
`doc/LICENCE.md`

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

- Open Knowledge Commons docs:
The active roadmap is`doc/ai/`

. End-user workflow is documented in`doc/ai/IMPLEMENTATION_PLAN.md`

. Self-hosted evaluation and rollout guidance is in`doc/ai/USER_GUIDE.md`

. Knowledge capture and curation policy is in`doc/ai/ADOPTION_GUIDE.md`

and`doc/ai/DATA_POOL.md`

. Storage and provenance design live in`doc/ai/TIERS.md`

,`doc/ai/STORAGE_MODEL.md`

, and`doc/ai/PROVENANCE.md`

. The browser and durable-artifact sequence lives in`doc/ai/SCHEMA.md`

. Validation coverage is tracked in`doc/ai/KNOWLEDGE_BROWSER_IMPLEMENTATION_PLAN.md`

. The project-level product summary for this fork lives in`doc/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](/BenSiv/fossil-scm/blob/master/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 are`claude`

,`codex`

,`gemini`

,`ollama`

, and`custom`

.`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 by`fossil agent embed`

,`semantic-index`

, and`retrieve`

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

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

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

, and`dev/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 configured`builtin_embedding_fallback`

, such as the bundled Ollama example using`curl`

against`/api/embed`

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

. This requires`OPENAI_API_KEY`

or`FOSSIL_AGENT_OPENAI_API_KEY`

. `qwen3.5:0.8b`

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

or`agent-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 as`prompt`

,`reply`

,`error`

,`progress`

, or`tool`

, 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 optional`after=`

filtering for incremental polling.`/agent-feedback`

records lightweight user feedback for the latest or selected terminal agent reply and stores it in`ai_chat_eval`

.- backend execution now records explicit
`running`

and`ok`

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`

, or`error`

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 as`useful`

or`not-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 calls`claude`

with`-p`

and`--model`

, and both flags can be overridden with`FOSSIL_AGENT_CLAUDE_PROMPT_FLAG`

and`FOSSIL_AGENT_CLAUDE_MODEL_FLAG`

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

and set`agent-model`

to`auto`

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

. By default it calls`gemini`

with`--prompt`

and`--model`

, and both flags can be overridden with`FOSSIL_AGENT_GEMINI_PROMPT_FLAG`

and`FOSSIL_AGENT_GEMINI_MODEL_FLAG`

.

`make test`

runs the Tcl regression suite through
[ tst/tester.tcl](/BenSiv/fossil-scm/blob/master/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`

, and`eval-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`

on`agentchat`

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 the`json`

package from Tcllib installed.`set-manifest`

and`unversioned`

: Tcl must have the`sha1`

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 current`fossil 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
```