https://github.com/dd3ok/lucid
Skill-first context hygiene toolkit for AI agents
https://github.com/dd3ok/lucid
agent-skills ai-agents chatgpt claude-code codex context-engineering context-hygiene gemini-cli memory-gc openai openclaw prompt-debt
Last synced: 19 days ago
JSON representation
Skill-first context hygiene toolkit for AI agents
- Host: GitHub
- URL: https://github.com/dd3ok/lucid
- Owner: dd3ok
- License: mit
- Created: 2026-05-17T16:23:11.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-04T04:27:55.000Z (20 days ago)
- Last Synced: 2026-06-04T05:24:26.638Z (20 days ago)
- Topics: agent-skills, ai-agents, chatgpt, claude-code, codex, context-engineering, context-hygiene, gemini-cli, memory-gc, openai, openclaw, prompt-debt
- Language: Python
- Size: 282 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Lucid
[](https://github.com/dd3ok/lucid/actions/workflows/validate.yml)
Skill-first context hygiene toolkit for AI agents.
Lucid helps agents audit and plan cleanup for stale, over-specific,
contradictory, unsafe, or obsolete agent-facing context.
## Why
Agents do not need more memory by default. They need cleaner, smaller, current,
source-of-truth aligned context.
## What Lucid Is Not
- Not a memory bank
- Not a conversation summarizer
- Not a deletion bot
- Not a general documentation writer
- Not a code refactoring tool
## Install
Lucid is distributed from the canonical skill folder `skills/lucid/`.
Runtime-specific installs should symlink or copy that folder; they are not
separate sources of truth.
### Codex
User skill:
```bash
mkdir -p ~/.agents/skills
ln -s /path/to/lucid/skills/lucid ~/.agents/skills/lucid
```
Codex reads user skills from `$HOME/.agents/skills`, repository skills from
`.agents/skills` directories between the current working directory and the
repository root, and admin skills from `/etc/codex/skills`. Some hosts may also
expose a `CODEX_HOME`-specific skill root; treat that as a host-specific
convention, not the documented Codex install path.
Repository-local skill for a cloned workspace:
```bash
mkdir -p .agents/skills
ln -s ../../skills/lucid .agents/skills/lucid
```
Reusable Codex plugin distribution is separate from this raw skill folder. If
you package Lucid as a Codex plugin, include a manifest at
`/.codex-plugin/plugin.json` that points at the plugin's
`skills/` directory instead of treating
`dist/lucid-skill.zip` as a plugin archive.
### Claude Code
```bash
mkdir -p ~/.claude/skills
ln -s /path/to/lucid/skills/lucid ~/.claude/skills/lucid
```
### Gemini CLI
User skill:
```bash
mkdir -p ~/.gemini/skills
ln -s /path/to/lucid/skills/lucid ~/.gemini/skills/lucid
```
Cross-agent alias:
```bash
mkdir -p ~/.agents/skills
ln -s /path/to/lucid/skills/lucid ~/.agents/skills/lucid
```
### Hermes
```bash
mkdir -p ~/.hermes/skills/productivity
ln -s /path/to/lucid/skills/lucid ~/.hermes/skills/productivity/lucid
```
Reload skills or start a new Hermes session after installing. Prefer a copied
or symlinked skill directory for Lucid's multi-file layout; direct URL installs
are appropriate only for single-file `SKILL.md` skills.
### OpenClaw
Managed agent skill:
```bash
openclaw skills install /path/to/lucid/skills/lucid --agent mozzi --as lucid
openclaw skills info lucid --agent mozzi --json
```
Managed global skill:
```bash
openclaw skills install /path/to/lucid/skills/lucid --global --as lucid
openclaw skills info lucid --json
```
Manual workspace or `~/.openclaw/skills` symlinks also work, but managed
installs make the active `baseDir`, visibility, and requirements easier to
inspect.
### Runtime Policy Packs
Set `policy_pack` in `lucid.config.json` when auditing runtime-specific
context layouts:
```json
{
"version": 1,
"policy_pack": "codex"
}
```
Supported built-in packs are `generic`, `codex`, `claude`, `gemini`,
`hermes`, and `openclaw`.
Lucid scans only files whose resolved paths remain under `--root`. Global or
home-directory skill installs such as `~/.agents/skills`, `~/.hermes/skills`,
or `~/.openclaw/skills` are not included in a repository audit unless you
audit a parent root that contains those runtime directories or vendor the skill
into the target root.
## Quick Start
From a target repository:
The repo-level `lucid.py` wrapper is for cloned repository usage. Packaged or
runtime-installed skills should invoke `/scripts/lucid.py`.
For OpenClaw managed installs, read `` from the `baseDir`
field in `openclaw skills info lucid --agent --json`.
```bash
python3 /path/to/lucid/lucid.py scan --root . --format terminal
python3 /path/to/lucid/lucid.py audit --root . --format terminal
python3 /path/to/lucid/lucid.py plan --root . --out .lucid/plan.md
python3 /path/to/lucid/lucid.py suggest --root . --out .lucid/suggested.patch
```
Lucid is read-only by default. It writes generated reports, plans, and patch
suggestions only under `.lucid/`.
Use `--config` with `scan`, `audit`, `plan`, `suggest`, or `verify` to load an
explicit config file inside the target repository.
Use `lucid.ignore.json` at the target repository root to suppress reviewed
false positives by `rule`, `path`, and required `reason`.
## Usage Boundaries
Use `scan`, `audit`, and `plan` for repository or workspace context hygiene
reviews. Lucid is a review aid, not a general workspace pass/fail gate.
`verify --strict` is primarily for validating Lucid's own skill/package
structure and strict entrypoint limits.
Stale-reference findings are root-scoped. Template paths such as
`memory/YYYY-MM-DD.md` and environment-rooted paths such as
`$HOME/.watchlist/WATCHLIST.md` are treated as intentional non-local
references rather than missing repo files.
Memory findings are retention review signals. A finding in `MEMORY.md` does not
mean the memory should be removed automatically; decide whether it is still
useful as durable context.
For initial adoption, install Lucid in a single managed agent or runtime before
installing it globally across multiple runtimes.
## CI Reporting
Generate report-only SARIF output for code scanning or CI artifacts:
```bash
python3 /path/to/lucid/lucid.py audit --root . --format sarif --out .lucid/audit.sarif
```
Emit report-only GitHub Actions annotations for inline CI findings:
```bash
python3 /path/to/lucid/lucid.py audit --root . --format github-actions
```
GitHub Actions example: [docs/github-actions.md](docs/github-actions.md)
The recommended CI path is to checkout or vendor Lucid and run the local Python
script directly. Artifact and SARIF uploads remain explicit workflow choices.
## Package
Build a local/runtime extracted skill archive:
```bash
python3 scripts/package-skill.py
python3 scripts/package-skill.py --target raw-local
```
The archive is written to `dist/lucid-skill.zip` and contains the canonical
`skills/lucid/` skill contents with repo-level docs, evals, fixtures, generated
outputs, and cache files excluded.
The zip archive has `SKILL.md` at its root. Runtimes that install from a
directory, such as OpenClaw local installs or Hermes multi-file skills, should
extract the archive first and install the extracted directory. Codex plugin
distribution requires plugin metadata and is not represented by this raw skill
archive.
Build an OpenAI hosted skill upload archive:
```bash
python3 scripts/package-skill.py --target openai-hosted --out dist/openai/lucid.zip
```
The OpenAI hosted archive wraps the same skill files under a single top-level
`lucid/` folder, so the zip contains `lucid/SKILL.md`,
`lucid/scripts/lucid.py`, `lucid/references/`, and `lucid/agents/openai.yaml`.
Keep this shape separate from the raw local archive, which intentionally keeps
`SKILL.md` at the archive root.
## Usage
Ask your agent:
```text
Audit this repo for prompt debt and stale agent-facing context.
```
For direct terminal usage, see Quick Start.
## Design
- `SKILL.md` is a short router.
- `references/` contains judgment rules.
- `lucid.py` is a thin CLI wrapper.
- `action.yml` is experimental and not the primary CI surface.
- `skills/lucid/scripts/lucid.py` performs deterministic checks.
- `evals/fixtures` prevent regressions.
- `.lucid/plan.md` is generated before any edit.
More detail: [docs/design-rationale.md](docs/design-rationale.md)
Product contract: [docs/product-design.md](docs/product-design.md)
Output schema: [docs/output-schema.md](docs/output-schema.md)
Policy packs: [docs/policy-packs.md](docs/policy-packs.md)
GitHub Actions usage: [docs/github-actions.md](docs/github-actions.md)
Security policy: [SECURITY.md](SECURITY.md)
Release checklist: [docs/release-checklist.md](docs/release-checklist.md)
## Roadmap
See [docs/product-design.md](docs/product-design.md#roadmap) for the detailed
roadmap.
- v0.1: read-only scanner/planner
- v0.2: skill packaging, CLI wrapper, basic scoring, terminal summaries,
diff-only suggestions, SARIF
- v0.3: policy packs, config validation, source graph, provenance, redaction
preview metadata, migration target hints
- v0.4: runtime compatibility docs, hosted package targets, usage boundaries
- v1.0: stable schemas and optional CI recipes
## Status
Lucid v0.4.0 is a public alpha. The current package is a read-only context
hygiene scanner, planner, reporter, and review-only patch suggestion tool for
local validation before applying cleanup changes.
## License
MIT. See [LICENSE](LICENSE).