CLEAR Context OS

Knowledge that maintains itself —
so your AI doesn't act on what was true last month.

Install  ·  What it does  ·  Wiki zone  ·  What ships  ·  Getting Started

Your AI had perfect context — two weeks ago. Then your strategy shifted, three meetings redefined priorities, and the docs you wrote on Monday are wrong by Friday. CLEAR Context OS is the maintenance layer your second brain never had: ownership boundaries enforced mechanically, staleness surfaced on a schedule, drift propagated across linked docs, a dispatcher that learns from your clicks. One source of truth per topic. Searchable. Task-aware. Never silently stale.

Install

Easiest — let Claude do it. Open Claude Code in any directory and paste:

"Install BCOS from https://github.com/walm00/business-context-os and walk me through onboarding."

Claude clones the repo, picks the right install path for your platform (Windows/macOS/Linux), runs setup, and steps straight into onboarding. No prereq checks to debug — if something's missing, Claude resolves it interactively.

Or manually, two commands:

curl -fsSL https://raw.githubusercontent.com/walm00/business-context-os/main/install.sh -o /tmp/bcos-install.sh
bash /tmp/bcos-install.sh

(Requires bash, curl, and tar on PATH — fine on macOS/Linux and on Windows under WSL or Git Bash. Two steps instead of a single bash <(curl …) pipe so Claude Code's permission gate auto-approves both commands — you don't need to drop out to a terminal.)

Drop anything you already have — SOPs, brand docs, meeting notes, exports — into docs/_inbox/ (skip if you're starting fresh). Then open Claude Code in that repo and say:

"Launch BCOS onboarding."

That's the only prompt you need. Onboarding inspects your inbox, scans the rest of the repo, asks one Q&A round, and proposes the architecture for review. Works the same whether the repo is fresh or already full of context.

From zero to running

  INSTALL  →  DISCOVER  →  ALIGN  →  SCHEDULE  →  RUNNING

Simple, guided, automatic. Claude walks you through each step — you review, you decide. Nothing deleted along the way — originals preserved or archived, never silently overwritten.

What it does

Stops context rot in three ways:

The folder tells the LLM what to trust. Claude reads the path before the content: docs/*.md = canonical, _planned/ = not yet real, _archive/ = history, _inbox/ = unprocessed, _collections/ = verbatim evidence, _wiki/ = explanatory. The hierarchy is the trust signal — fewer tokens spent re-deciding, no chance of treating an archived draft as today's truth.

docs/
├── *.md                  ← canonical data points (one source of truth per topic)
├── document-index.md     ← auto-generated TOC
├── current-state.md      ← what's true right now + what changed recently
├── table-of-context.md   ← high-level cluster map for orientation
├── _inbox/               ← drop zone — Claude triages on demand
├── _planned/             ← polished ideas, not yet real
├── _archive/             ← superseded — kept, not deleted
├── _collections/         ← verbatim evidence (invoices, contracts, transcripts)
│   └── <type>/_manifest.md   (each collection has a manifest)
├── _wiki/                ← derivative knowledge (how-tos, source summaries)
│   ├── pages/            ← user-authored explainers
│   ├── source-summary/   ← external captures with citation banners
│   ├── raw/              ← original artifacts (PDFs, HTML)
│   └── queue.md          ← URLs awaiting fetch
└── _bcos-framework/      ← framework docs — never user content
    ├── architecture/     ← 12 zone + system architecture docs
    ├── methodology/      ← 5 CLEAR + ownership + standards docs
    ├── patterns/         ← 8 project-type starting templates
    └── templates/        ← 15 frontmatter / schema / starter files

The wiki zone

Inspired by Karpathy's LLM Wiki approach — give the LLM a wiki of your knowledge, the way you'd brief a smart new hire.

Save anything to the wiki, from anywhere:

/wiki run https://stripe.com/docs/api          ← fetch a URL, summarize, cite
/wiki create from /Users/me/Downloads/spec.pdf ← extract a PDF, link to the binary
/wiki promote docs/_inbox/meeting-notes.md     ← turn an inbox capture into a wiki page

The wiki holds how-tos, runbooks, glossaries, source summaries, post-mortems, decision logs — derivative knowledge that explains and supports your canonical data points. Every page cites what it builds on. Stale pages surface automatically when their sources advance.

Wiki content is searchable alongside the rest of your context:

/context search "stripe billing"       ← cross-zone search, ranked by source-of-truth
/context bundle market-report:write    ← curated bundle for a specific task

The dashboard

A local cockpit at http://127.0.0.1:8091 that shows your system at a glance — no third-party services, no telemetry, no logins.

python .claude/scripts/bcos-dashboard/run.py

The dashboard is read-mostly: data flows from the dispatcher's diary, the schedule config, and the canonical context index. Writes (mark-done, schedule preset, auto-commit toggle, file fix) go through dedicated POST endpoints.

Requirements

• Claude Code (desktop app, CLI, or web)
• Python 3.8+ on PATH
• bash (default macOS bash 3.2 is fine)

Updating

python .claude/scripts/update.py

Refreshes framework files only — skills, hooks, scripts, templates. Your docs/ and .private/ are never touched.

Maintenance

One scheduled task per repo. The dispatcher reads schedule-config.json, runs the jobs due today, writes one consolidated digest at docs/_inbox/daily-digest.md, and surfaces findings as one-click cards in the dashboard.

You can tune any of it in plain English:

"Run the audit twice a week." · "Move dispatcher to 08:30." · "Turn off deep daydream."

The system learns from your clicks. After three consistent uses of the same fix, the dashboard pre-selects it as a "✨ suggested" action — you accept or reject. Reversals trigger an automatic safety brake.

CLEAR — the methodology

Five principles, one rule each:

• C — Contextual Ownership · one document owns each topic. No duplicates.
• L — Linking · reference sources; don't copy them.
• E — Elimination · consolidate; don't keep two versions.
• A — Alignment · context that doesn't support decisions doesn't belong.
• R — Refinement · structured maintenance, not ad-hoc fixes.

The whole framework is the mechanical implementation of these five rules.

What ships

Everything below installs as one repo drop-in. No third-party services, no logins, no telemetry — all state lives in your .claude/ and docs/ folders.

Every script and skill is documented at the source. Every job has a reference doc under .claude/skills/schedule-dispatcher/references/job-*.md. Every typed-event finding maps to a renderer in the dashboard cockpit. Adding a new check means dropping a cmd_*.py or run_*.py, registering it in one map, and the dashboard picks it up.

Contributing

Contributions welcome — open an issue or submit a PR targeting the dev branch. CI runs frontmatter, reference, and ecosystem-integration checks on every PR.

The fastest contribution path is lessons learned. As you use the system it captures insights; if you find one universal, contribute it back.

Origin

Built by Guntis Coders after two years of operating context systems in production. The CLEAR methodology emerged from a practical problem: AI context degrades silently, and no amount of one-time documentation prevents it. The solution required a system — ownership boundaries, automated maintenance, self-learning, and structured reflection.

Background: What is the Table of Contexts and why does it matter.

License

MIT