blabl

blabl is a Fossil-native coding workbench for generating code, improving existing code, and improving its own ability to generate code.

Its final purpose is simple:

Become an ever-improving coding tool.

The project starts from a practical observation: a computer becomes useful for this purpose when it has code and storage. Today, Crystal is the representative tool for code, Fossil is the representative tool for storage and project memory, and a Linux-provisioned system is the current operating ground. These choices are pragmatic, not sacred. Each should become more interchangeable when doing so improves the workbench without destroying present efficiency.

The name blabl started as a thought-experiment regarding Bluetooth Low-Energy (BLE) based avatars. Part of improving this tools coding ability is to learn how to provide it with good guidance, somewhat taking on the personality (functional blind-spots) projected by the user. In this sense and more, it is indeed envisioned as an avatar of sorts. A backgrounder on the thought experiment would be useful here.

Why this exists

Human contributors and language models can both produce valuable work. They can also produce work of uneven quality. blabl should tolerate that reality without becoming vague, brittle, or unreviewable.

Overall failure is treated as catastrophic. The project therefore follows three anti-failure axioms:

Clarity

Each part should become easier to name, understand, and judge.

A part may have an imperfect or provisional purpose, but it should have a stated purpose. As understanding improves, that purpose can be clarified, subdivided, revised, or replaced.

Interchangeability

Each part should move, over time, toward being replaceable by something better.

Interchangeability does not mean everything must be abstract immediately. It means the workbench should avoid unnecessary entanglement, expose useful seams, and make replacement possible when replacement becomes worthwhile.

Accountability

Each part should be judged against its currently stated purpose.

The purpose may later change, but while it is the stated purpose, it is binding. A contribution is not complete merely because it changes code. It must also say what it is trying to accomplish and provide evidence that it does so.

No contribution without a claim; no claim without evidence.

The workbench model

blabl is not just a chat interface and not just a task runner. It is a workbench: a structured place where code, storage, contributors, evidence, review, replacement, and improvement can meet.

The workbench should make it natural to:

1. state a purpose,
2. generate or change code,
3. attach evidence,
4. record weaknesses,
5. review the result,
6. improve the part or the purpose,
7. repeat with better judgment.

This is similar to a real free market in the deeper sense: not laissez-faire, not "anything goes," but a setting where comparison, exchange, replacement, and correction are possible because claims and responsibilities are clear.

On the surface, the simpler image is enough:

A coding workbench whose parts become clearer, more interchangeable, and more accountable over time.

What blabl does

blabl routes coding work through a Fossil-centered workflow.

It is being built to:

• let an authenticated Fossil user work from a browser UI,
• preserve useful conversation and task context,
• turn tickets, prompts, or thread turns into queued coding tasks,
• run model-backed work in isolated Fossil checkouts,
• use local Ollama models by default where practical,
• support hosted or OpenAI-compatible providers where useful,
• prefer native, structured tool calls over raw shell access,
• verify code changes with Crystal specs and other evidence patterns,
• record task reports, events, notes, risks, changed files, commands, and follow-up work,
• bring results back to Fossil branches, tickets, timeline, and review pages.

The goal is not blind autonomy. The goal is supervised improvement: model and human contributions should be visible, bounded, testable, reviewable, and replaceable.

Evidence patterns

Crystal specs are necessary evidence for behavior, but they are not sufficient evidence for every purpose.

Purpose determines evidence.

Purpose claim	Default evidence pattern
"This behaves correctly"	Crystal specs
"This is formatted consistently"	crystal tool format --check
"This is faster"	A repeatable benchmark pattern
"This is simpler"	A before/after explanation and a smaller surface area
"This is clearer"	A clearer name, boundary, document, or example
"This is more interchangeable"	A seam, adapter, replacement test, or reduced coupling
"This is safer"	A constrained interface, redaction check, permission check, or failure test
"This improves code generation"	Comparison on defined generation tasks
"This improves accountability"	A traceable claim, evidence, review record, and follow-up path

These patterns should begin as conventions. Pave the cowpaths: when a practice repeatedly helps, name it, document it, support it, make it easy, and only later make it enforceable.

Missing evidence should be visible as weakness, not hidden as certainty. When two approaches are available, prefer the one with better evidence.

Contribution shape

A meaningful contribution should tend toward this shape:

purpose:  What is this for?
change:   What changed?
evidence: Why should we believe it works for that purpose?
weakness: What is still unclear, untested, or risky?
next:     What would improve the claim, evidence, or implementation?

Not every contribution will satisfy this perfectly. The workbench should accept imperfect contributions from reasonable actors, human or model, while making their weaknesses legible and improvable.

Current implementation shape

The current implementation is centered on these surfaces:

• Fossil: source of truth for repository state, tickets, timeline, branches, docs, and review history.
• Crystal: preferred language for maintained application code.
• /ext/chat: authenticated browser surface for threads, chat, task coordination, reports, and review actions.
• bin/task-worker: worker path for queued chat and coding tasks.
• bin/agent-tool: CLI/operator surface for native tools, supervision, and testing.
• bin/mcp-server: structured tool surface for external assistants and MCP-capable clients.
• ext/docs: generated Crystal API documentation exposed through the Fossil-adjacent web surface.
• Runtime storage: task queues, logs, reports, checkouts, provider configuration, and transient state stored outside normal versioned source files.

The tool should keep these surfaces aligned without pretending they are identical. A browser user should see constrained product actions. A worker should have the native tools it needs to complete tasks. A CLI operator should have enough access to inspect, test, and repair. External assistants should receive structured capabilities rather than unconstrained shell access wherever practical.

Development direction

The project should continue moving toward:

• durable threads and resumable context,
• task records linked to tickets, thread turns, reports, events, notes, branches, and commits,
• clear review pages showing what is safe, blocked, risky, or ready,
• provider-independent task status and result shapes,
• local-first model execution with bounded escalation to stronger hosted models when justified,
• stronger native tools for reading, patching, formatting, verifying, benchmarking, committing, and reviewing,
• evidence patterns that begin as conventions and mature into controls,
• better measurement of whether changes improve the workbench as a coding tool.

Practical rules

• Keep changes small and reviewable.
• Prefer Crystal for maintained application code.
• Prefer Fossil-native integration where it strengthens project memory and review.
• Keep secrets, tokens, passwords, and session material out of versioned files.
• Run model tasks in isolated checkouts.
• Prefer structured native tools over raw shell access.
• Treat generated code as incomplete until its purpose and evidence are recorded.
• Prefer evidenced paths over unevidenced paths.
• Record weak evidence so future work can strengthen it.
• Make interchangeability real when the current level of efficiency can afford it.

Plain-language causes

This project can be described through four causes:

Cause	Plain-language answer
Material cause	A computer needing code and storage to become useful; currently Linux, Crystal, and Fossil.
Formal cause	An ever-improving coding workbench whose parts become clearer, more interchangeable, and more accountable over time.
Efficient cause	Reasonable human and model contributors acting through built-in pressures toward clarity, interchangeability, and accountability.
Final cause	To be an ever-improving coding tool.

The causes do not prove the goal from neutral facts. The goal is chosen. Once chosen, the axioms guide whether the workbench is becoming more robust or drifting toward failure.

API Configuration

To enable model-backed consults and tasks, you must provide API keys via the Fossil web UI. These keys are stored in the Fossil DB config table, not in environment files.

1. Open the Fossil web interface.
2. Navigate to the Secrets form (or the configuration section where secrets are managed).
3. Add the following keys as needed:
   • ANTHROPIC_API_KEY: Required for Claude consults.
   • OPENAI_API_KEY: Required for OpenAI consults.
   • OLLAMA_CODEX_CONSULT_API_KEY: Required for the specific consult mechanism.

Lessons learned from Ollama-Codex

Ollama-Codex was the first implementation and is still on-going development. This project will be developed alongside it, providing A/B testing and a slightly different scope as this evolves into more of an avatar.

Here are some lessons.

1. Do not allow storage of any state information outside of the repository database, including environment variables, with the exception of checkouts, intermediate build artifacts and final executable artifacts.
2. Make better use of Fossil-native schemas top-level interfaces, like chat, tickets, and wiki.
3. A good LLM agent is more than just a collection of tools and an interface to a model, partially because it needs to guide the model mechanically to give it the greatest possibility of success.
4. An improved collection of tools and good guidance from the agent can indeed enable an otherwise less-capable model in this context to succeed at coding.

Project state

blabl is under active development. The current visible direction is to replace fragile coordination through external chat, CLI sessions, and tmux panes with a Fossil-hosted web UI that can preserve context, coordinate model-backed tasks, show progress, and support review.

The workbench should become useful before it becomes general. Interchangeability is an ideal, but the priority of replacing any current choice is dictated by whether the current state has enough efficiency to support that replacement.