Adapting Fossil-scm as a platform for AI agentic workflow

Fossil-scm, a distributed version control system used since 2007, has been adapted as a platform for AI agentic workflows, adding native support for chat and embedding backends through its settings system. The fork, maintained by BenSiv, introduces commands like `fossil agent verify`, supports providers including Ollama, Codex, Gemini, and Claude, and includes extensive documentation under `doc/ai/` for implementation, user guidance, and storage design.

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