Skip to content

README.md

Latest commit

 

History

History
335 lines (247 loc) · 19.3 KB

README.md

File metadata and controls

335 lines (247 loc) · 19.3 KB

Codex Workspace

Codex Workspace favicon

Codex Workspace is a local-first system for working across many standalone repositories as one coherent environment. It gives you shared discovery, runtime control, memory, docs, and agent tooling without forcing those repos into a monorepo or one shared dependency tree.

In practice, that means:

  • many repos can feel like one working system without becoming one codebase
  • local context can survive repo switches, handover updates, and long gaps between sessions
  • shared memory, docs, and tooling can sit above the repos without flattening their runtime models

Tool-agnostic context. Whether you use Codex, Cursor, Claude, or mix assistants, the same tracked docs, manifests, optional generated side-load summaries under cache/context/, and Workspace Hub give you a stable place to resume work when you switch tools—without rebuilding context from scratch. See docs/20-ai-context-side-load.md and Context for agents below.

What Exists Today

Workspace Hub

The most concrete product in this repo today is Workspace Hub, a local control plane for mixed-stack workspaces. It scans sibling repos, classifies them conservatively, shows runtime and metadata state, and provides start, stop, open, and preview actions without forcing every repo into one toolchain. It complements the filesystem-first docs and scripts rather than replacing them.

Codex Workspace cover

Around that, the workspace turns the usual pile of local scripts, scattered notes, and one-off agent setup into a more deliberate system.

The workspace repo around it provides:

  • a predictable folder layout for mixed stacks
  • shared caches and helper tooling
  • lightweight workspace metadata and manifests
  • a tracked capability lifecycle for reviewed upstream references, optional abilities, and core services
  • a filesystem-first context model for docs, manifests, and agent guidance
  • a practical way to resume work across multiple repos without reconstructing context from scratch

What's included (and why)

Area What it is Why
docs/ Canonical handover pack, indexes, and deep docs Single source of truth for workspace behavior and conventions
repos/ Standalone clones (including workspace-hub/) Each project stays its own repo with its own dependencies
tools/ Scripts, manifests, optional core services (e.g. MemPalace), MCP helpers Shared automation without merging unrelated installs
cache/ Shared stores (npm/pnpm, generated context, service artifacts) Speed and repeatability without a monorepo node_modules
shared/ Workspace metadata, standards, per-user MemPalace state Durable state that is not duplicated inside each repo
repos/workspace-hub/ Hub app (React + API) Discovery, runtime control, manifests, previews, and Workspace memory UI
Manifests & .workspace/ project.json and similar Explicit runtime when inference is not enough

For layout detail, see Workspace layout and How it works.

Who It's For

  • People managing many independent local repos across frontend, WordPress, PHP, static, and utility stacks.
  • Contributors who want a practical workspace structure plus a concrete app surface in repos/workspace-hub/.
  • Teams who want local runtime behavior to stay explicit instead of hiding everything behind one central toolchain.

Who It's Not For

  • Teams looking for one shared dependency graph across unrelated repos.
  • Setups that expect Docker or a reverse-proxy layer to be mandatory for every project.
  • Projects that already want a full monorepo with centralized installs and one runtime model.

Why This Instead Of A Monorepo

  • Repos stay independently runnable on their own terms.
  • Caches can be shared without sharing installs.
  • Local runtime behavior stays explicit and inspectable.
  • WordPress, Vite, static, PHP, and utility repos can coexist without pretending they all want the same workflow.
  • Shared memory, docs, and tooling can span the whole workspace without pretending the codebases are one project.

The goal is not to make many repos look like one dependency graph. The goal is to make them feel like one working environment.

Quick Start

If you want to try the concrete product first, run Workspace Hub:

cd repos/workspace-hub
pnpm install
pnpm dev

The Hub still shows the Workspace memory surface, but MemPalace actions are temporarily paused because tools/bin/workspace-memory is disabled during the write-lock and corpus-size review. Archive files are also hidden from the default Hub summary and only load when you explicitly enable archived items in Repo Discovery. The dashboard also exposes installable abilities and core services through the Workspace Capabilities panel, and supports a persisted split versus discovery-first repo layout.

If you want the fuller workspace path after that:

Repo-specific launchers can also live under tools/local/commands/. Those workspace launchers should keep the host on 127.0.0.1, prefer a repo-specific port range, and step to the next free port instead of randomizing the address. For example, tools/local/commands/Run Knowledge Palace UI.command starts the Knowledge Palace local web UI from the workspace root.

How To Contribute

Looking For Help

  • Docs clarity and repo-entry improvements.
  • Repo classification and manifest examples.
  • Workspace Hub UX and empty-state polish.
  • Runtime diagnostics and contributor-friendly troubleshooting.
  • Templates and scripts that reduce workspace setup friction.

Contribution Areas

  • Docs clarity
  • Repo classification and manifests
  • Workspace Hub UX
  • Runtime diagnostics
  • Templates and scripts

Now / Next / Later

  • Now: Docs clarity, Workspace Hub UX, repo classification, manifest examples, and script ergonomics are stable enough for outside contribution.
  • Next: Capability-surface polish, observability visibility, screenshot and preview reliability, and tighter contributor verification paths.
  • Later: Broader capability promotion and deeper workspace-memory flows after the current public surfaces settle.
  • Out of scope: Shared dependency installs across unrelated repos, mandatory reverse-proxy or mapped-host tooling for every repo, or forcing every repo through one runtime model.

Why It Exists

This repo exists to keep local development practical when your machine contains many unrelated repos.

  • repos stay independently runnable
  • caches can be shared without sharing installs
  • local runtime behaviour stays explicit
  • WordPress, Vite, static, PHP, and utility repos can coexist cleanly
  • optional mapped-host or proxy previews stay optional, not a hidden requirement

How It Works

Codex Workspace addresses that with a practical filesystem-first model:

  • keep repo facts in normal tracked files
  • keep generated summaries in cache/
  • keep core workspace services in tools/ with durable per-user state in shared/
  • keep reusable skills portable across agents
  • keep machine-specific memory and secrets local
  • keep retrieval and repo classification explainable

Core Principles

  • Do not merge unrelated repos into one dependency structure.
  • Share caches, not installs.
  • Treat each repo as independently runnable.
  • Prefer direct local runtime for frontend and dev-server projects.
  • Keep WordPress handling pragmatic.
  • Use lightweight manifests where explicit runtime behaviour helps.

Workspace Layout

Codex Workspace/
├── docs/
├── repos/
│   └── workspace-hub/
├── tools/
├── cache/
├── shared/
└── workspace.code-workspace

docs/ is the canonical documentation surface. shared/ is for workspace metadata such as shared/repo-index.json and shared/standards.md, not duplicated doc mirrors.

Use the starter files when you need explicit repo metadata:

Recommended maintainer extras:

  • gh is recommended when you maintain forks, PRs, or reviewed upstream mirrors
  • gh auth login is optional maintainer setup, not part of the baseline release gate
  • optional local reverse-proxy or mapped-host tooling only when specific repos benefit from a shared local front door

Documentation

Start here:

Deeper docs:

Supporting references:

When a workspace-wide feature lands, update the public surfaces in the same slice:

  • README.md
  • docs/README.md
  • docs/CHANGELOG.md
  • relevant repo-local docs such as repos/workspace-hub/README.md
  • optional navigation pages under docs/wiki/ when public navigation should expose the feature

Context For Agents

Codex Workspace treats agent-facing context as normal workspace content rather than a hidden prompt blob.

The practical model is:

  • tracked resources such as repo docs, READMEs, and manifests
  • official Codex repo-local skills stored in .codex/skills/, with .agents/skills/ supported as a workspace compatibility mirror and shared skill sources/templates kept in normal tracked folders
  • root .agents/skills/ used only as a manifest-managed TomeVault distribution mirror
  • generated context summaries under cache/context/
  • optional local workflow-state folders such as .cognetivy/ kept separate from canonical tracked docs
  • local-only memory and MCP config kept separate from tracked repo content
  • a small official MCP v1 profile set for Codex, installed through workspace-owned scripts instead of ad hoc one-off setup

Side-load summaries are now generated with tools/scripts/generate-context-cache.sh into ignored cache/context/workspace/ and cache/context/repos/ paths. They are optional L0 and L1 cache files, not canonical workspace documentation.

The current MCP v1 support set is intentionally small: OpenAI Docs, Context7, Playwright, Chrome DevTools, and GitHub.

This keeps context easier to inspect, reason about, and adapt across tools while keeping each repo independently runnable.

Default token-saving stance: read docs/HANDOVER.md for current state, use only cache/context/.../entry.md when a generated packet helps, keep Workspace Hub search in thin mode, leave Hub archive files hidden, prefer the safe-readonly MCP profile for routine repo work, and avoid docs/archive/, ref/, screenshots/, cache/, and shared/mempalace/ unless the task explicitly needs them. See docs/21-agent-token-budget.md.

Tracked repo knowledge belongs in public docs, manifests, and portable skills. Local operator memory belongs in ignored local files until it becomes stable enough to promote into tracked project guidance.

To keep stale information out of the workspace, dated local verification results should replace vague "latest" claims. Generated context under cache/ is useful evidence, but tracked docs and manifests stay canonical. External service status, including TomeVault profile or scan counts, should be checked live before it is recorded as current.

Workspace memory is temporarily disabled. tools/bin/workspace-memory now exits without running MemPalace closeout, ingest, search, wake-up, export, or graph commands while the write-lock and corpus-size behavior is reviewed.

Current closeout guidance:

  • record repo closeout in tracked repo docs such as README.md, HANDOVER.md, or DESIGN.md
  • record workspace closeout in docs/HANDOVER.md and docs/CHANGELOG.md
  • use generated context-cache summaries under cache/context/ only as optional local side-load material, not as canonical memory

For local cleanup, use tools/scripts/cleanup-sync-noise.sh first in its default dry-run mode. Pass --run only for targeted macOS/sync-noise removal; do not use broad git clean flows for workspace cleanup.

When a capability becomes part of how the whole workspace operates, prefer a core-service shape:

  • tracked runtime code in tools/
  • durable per-user state in shared/
  • disposable artifacts in cache/

See:

Current workspace source taxonomy:

  • reference-only lives under tools/ref/
  • ability lives under repos/abilities/<slug>/
  • repo-level adoption lives under normal repos/...
  • core service lives under tools/<name>/ with durable state in shared/<name>/<user>/ and disposable state in cache/<name>/<user>/

External skill catalogs such as openai/skills, the canonical google-labs-code/design.md spec/tooling, and example catalogs such as VoltAgent/awesome-design-md should be treated as optional reviewed sources, not vendored workspace dependencies.

  • install only the specific skills that solve a real workflow need
  • prefer local skill installation via Codex tooling such as $skill-installer
  • for repo-level Codex discoverability, prefer tracked .codex/skills/ and keep .agents/skills/ only when repo-local compatibility mirroring helps
  • keep workspace-wide reusable skill sources in shared/skills/ and starter templates in tools/templates/skills/
  • use tools/scripts/sync-tomevault-skills.sh to refresh the root .agents/skills/ public distribution mirror from tools/manifests/tomevault-skills.json; do not install TomeVault Relay or commit generated TomeVault format files by default
  • treat google-labs-code/design.md as the canonical repo-level DESIGN.md standard and use tools/scripts/design-md.sh to initialize, lint, and diff repo-owned DESIGN.md files
  • keep repo-root DESIGN.md optional and per-repo, recommended mainly for UI-heavy repos rather than the whole workspace
  • keep the managed VoltAgent DESIGN.md catalog as an optional example ability under repos/abilities/voltagent-awesome-design-md and copy only the specific example files a repo actually needs
  • use tools/scripts/capture-site-reference.sh when a repo needs a conservative httrack-based public-site reference capture plus a repo-local acquisition note under ref/httrack/
  • use tools/scripts/use-design-md.sh only for the VoltAgent example catalog mirror under cache/design-md/catalog/
  • keep third-party orchestration layers and generated agent setup local-only unless there is a strong reason to publish them
  • do not add the whole upstream skill catalog to repos/, tools/, or as a submodule unless there is a very specific maintenance reason

If you want local reviewed copies of official upstreams for comparison, keep snapshot-style references under tools/ref/, and use tools/scripts/manage-workspace-capabilities.sh for installable abilities and core services. tools/scripts/update-github-refs.sh remains only as the compatibility wrapper for update-only GitHub-ref flows.

Release Readiness

Use the non-destructive release gate before calling a workspace release stable:

tools/scripts/release-readiness.sh

The stable repo contract and .codex/ migration note live in docs/10-release-readiness.md.

Community

Current Status

The current baseline is a stable local workspace structure plus Workspace Hub 1.x, with enough documentation and tooling to keep mixed repos practical on one machine. Optional mapped-host or reverse-proxy previews remain optional.