About Fossil

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.

Documentation

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: doc/ai/ The active roadmap is doc/ai/IMPLEMENTATION_PLAN.md. End-user workflow is documented in doc/ai/USER_GUIDE.md. Self-hosted evaluation and rollout guidance is in doc/ai/ADOPTION_GUIDE.md. Knowledge capture and curation policy is in doc/ai/DATA_POOL.md and doc/ai/TIERS.md. Storage and provenance design live in doc/ai/STORAGE_MODEL.md, doc/ai/PROVENANCE.md, and doc/ai/SCHEMA.md. The browser and durable-artifact sequence lives in doc/ai/KNOWLEDGE_BROWSER_IMPLEMENTATION_PLAN.md. Validation coverage is tracked in doc/ai/TEST_PLAN.md. The project-level product summary for this fork lives in 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

AI Agent Configuration

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.

Basic Setup

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 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, dev/agents/fossil-gemini-agent.sh, and 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.

Testing

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, 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