{"id":50589659,"url":"https://github.com/dd3ok/lucid","last_synced_at":"2026-06-05T09:30:25.327Z","repository":{"id":360429726,"uuid":"1241634577","full_name":"dd3ok/lucid","owner":"dd3ok","description":"Skill-first context hygiene toolkit for AI agents","archived":false,"fork":false,"pushed_at":"2026-06-04T04:27:55.000Z","size":289,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T05:24:26.638Z","etag":null,"topics":["agent-skills","ai-agents","chatgpt","claude-code","codex","context-engineering","context-hygiene","gemini-cli","memory-gc","openai","openclaw","prompt-debt"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dd3ok.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T16:23:11.000Z","updated_at":"2026-06-04T04:27:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dd3ok/lucid","commit_stats":null,"previous_names":["dd3ok/lucid"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/dd3ok/lucid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dd3ok%2Flucid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dd3ok%2Flucid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dd3ok%2Flucid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dd3ok%2Flucid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dd3ok","download_url":"https://codeload.github.com/dd3ok/lucid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dd3ok%2Flucid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33939226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","chatgpt","claude-code","codex","context-engineering","context-hygiene","gemini-cli","memory-gc","openai","openclaw","prompt-debt"],"created_at":"2026-06-05T09:30:24.346Z","updated_at":"2026-06-05T09:30:25.321Z","avatar_url":"https://github.com/dd3ok.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lucid\n\n[![validate](https://github.com/dd3ok/lucid/actions/workflows/validate.yml/badge.svg)](https://github.com/dd3ok/lucid/actions/workflows/validate.yml)\n\nSkill-first context hygiene toolkit for AI agents.\n\nLucid helps agents audit and plan cleanup for stale, over-specific,\ncontradictory, unsafe, or obsolete agent-facing context.\n\n## Why\n\nAgents do not need more memory by default. They need cleaner, smaller, current,\nsource-of-truth aligned context.\n\n## What Lucid Is Not\n\n- Not a memory bank\n- Not a conversation summarizer\n- Not a deletion bot\n- Not a general documentation writer\n- Not a code refactoring tool\n\n## Install\n\nLucid is distributed from the canonical skill folder `skills/lucid/`.\nRuntime-specific installs should symlink or copy that folder; they are not\nseparate sources of truth.\n\n### Codex\n\nUser skill:\n\n```bash\nmkdir -p ~/.agents/skills\nln -s /path/to/lucid/skills/lucid ~/.agents/skills/lucid\n```\n\nCodex reads user skills from `$HOME/.agents/skills`, repository skills from\n`.agents/skills` directories between the current working directory and the\nrepository root, and admin skills from `/etc/codex/skills`. Some hosts may also\nexpose a `CODEX_HOME`-specific skill root; treat that as a host-specific\nconvention, not the documented Codex install path.\n\nRepository-local skill for a cloned workspace:\n\n```bash\nmkdir -p .agents/skills\nln -s ../../skills/lucid .agents/skills/lucid\n```\n\nReusable Codex plugin distribution is separate from this raw skill folder. If\nyou package Lucid as a Codex plugin, include a manifest at\n`\u003cplugin-root\u003e/.codex-plugin/plugin.json` that points at the plugin's\n`skills/` directory instead of treating\n`dist/lucid-skill.zip` as a plugin archive.\n\n### Claude Code\n\n```bash\nmkdir -p ~/.claude/skills\nln -s /path/to/lucid/skills/lucid ~/.claude/skills/lucid\n```\n\n### Gemini CLI\n\nUser skill:\n\n```bash\nmkdir -p ~/.gemini/skills\nln -s /path/to/lucid/skills/lucid ~/.gemini/skills/lucid\n```\n\nCross-agent alias:\n\n```bash\nmkdir -p ~/.agents/skills\nln -s /path/to/lucid/skills/lucid ~/.agents/skills/lucid\n```\n\n### Hermes\n\n```bash\nmkdir -p ~/.hermes/skills/productivity\nln -s /path/to/lucid/skills/lucid ~/.hermes/skills/productivity/lucid\n```\n\nReload skills or start a new Hermes session after installing. Prefer a copied\nor symlinked skill directory for Lucid's multi-file layout; direct URL installs\nare appropriate only for single-file `SKILL.md` skills.\n\n### OpenClaw\n\nManaged agent skill:\n\n```bash\nopenclaw skills install /path/to/lucid/skills/lucid --agent mozzi --as lucid\nopenclaw skills info lucid --agent mozzi --json\n```\n\nManaged global skill:\n\n```bash\nopenclaw skills install /path/to/lucid/skills/lucid --global --as lucid\nopenclaw skills info lucid --json\n```\n\nManual workspace or `~/.openclaw/skills` symlinks also work, but managed\ninstalls make the active `baseDir`, visibility, and requirements easier to\ninspect.\n\n### Runtime Policy Packs\n\nSet `policy_pack` in `lucid.config.json` when auditing runtime-specific\ncontext layouts:\n\n```json\n{\n  \"version\": 1,\n  \"policy_pack\": \"codex\"\n}\n```\n\nSupported built-in packs are `generic`, `codex`, `claude`, `gemini`,\n`hermes`, and `openclaw`.\n\nLucid scans only files whose resolved paths remain under `--root`. Global or\nhome-directory skill installs such as `~/.agents/skills`, `~/.hermes/skills`,\nor `~/.openclaw/skills` are not included in a repository audit unless you\naudit a parent root that contains those runtime directories or vendor the skill\ninto the target root.\n\n## Quick Start\n\nFrom a target repository:\n\nThe repo-level `lucid.py` wrapper is for cloned repository usage. Packaged or\nruntime-installed skills should invoke `\u003clucid-skill-dir\u003e/scripts/lucid.py`.\nFor OpenClaw managed installs, read `\u003clucid-skill-dir\u003e` from the `baseDir`\nfield in `openclaw skills info lucid --agent \u003cagent\u003e --json`.\n\n```bash\npython3 /path/to/lucid/lucid.py scan --root . --format terminal\npython3 /path/to/lucid/lucid.py audit --root . --format terminal\npython3 /path/to/lucid/lucid.py plan --root . --out .lucid/plan.md\npython3 /path/to/lucid/lucid.py suggest --root . --out .lucid/suggested.patch\n```\n\nLucid is read-only by default. It writes generated reports, plans, and patch\nsuggestions only under `.lucid/`.\n\nUse `--config` with `scan`, `audit`, `plan`, `suggest`, or `verify` to load an\nexplicit config file inside the target repository.\n\nUse `lucid.ignore.json` at the target repository root to suppress reviewed\nfalse positives by `rule`, `path`, and required `reason`.\n\n## Usage Boundaries\n\nUse `scan`, `audit`, and `plan` for repository or workspace context hygiene\nreviews. Lucid is a review aid, not a general workspace pass/fail gate.\n`verify --strict` is primarily for validating Lucid's own skill/package\nstructure and strict entrypoint limits.\n\nStale-reference findings are root-scoped. Template paths such as\n`memory/YYYY-MM-DD.md` and environment-rooted paths such as\n`$HOME/.watchlist/WATCHLIST.md` are treated as intentional non-local\nreferences rather than missing repo files.\n\nMemory findings are retention review signals. A finding in `MEMORY.md` does not\nmean the memory should be removed automatically; decide whether it is still\nuseful as durable context.\n\nFor initial adoption, install Lucid in a single managed agent or runtime before\ninstalling it globally across multiple runtimes.\n\n## CI Reporting\n\nGenerate report-only SARIF output for code scanning or CI artifacts:\n\n```bash\npython3 /path/to/lucid/lucid.py audit --root . --format sarif --out .lucid/audit.sarif\n```\n\nEmit report-only GitHub Actions annotations for inline CI findings:\n\n```bash\npython3 /path/to/lucid/lucid.py audit --root . --format github-actions\n```\n\nGitHub Actions example: [docs/github-actions.md](docs/github-actions.md)\n\nThe recommended CI path is to checkout or vendor Lucid and run the local Python\nscript directly. Artifact and SARIF uploads remain explicit workflow choices.\n\n## Package\n\nBuild a local/runtime extracted skill archive:\n\n```bash\npython3 scripts/package-skill.py\npython3 scripts/package-skill.py --target raw-local\n```\n\nThe archive is written to `dist/lucid-skill.zip` and contains the canonical\n`skills/lucid/` skill contents with repo-level docs, evals, fixtures, generated\noutputs, and cache files excluded.\nThe zip archive has `SKILL.md` at its root. Runtimes that install from a\ndirectory, such as OpenClaw local installs or Hermes multi-file skills, should\nextract the archive first and install the extracted directory. Codex plugin\ndistribution requires plugin metadata and is not represented by this raw skill\narchive.\n\nBuild an OpenAI hosted skill upload archive:\n\n```bash\npython3 scripts/package-skill.py --target openai-hosted --out dist/openai/lucid.zip\n```\n\nThe OpenAI hosted archive wraps the same skill files under a single top-level\n`lucid/` folder, so the zip contains `lucid/SKILL.md`,\n`lucid/scripts/lucid.py`, `lucid/references/`, and `lucid/agents/openai.yaml`.\nKeep this shape separate from the raw local archive, which intentionally keeps\n`SKILL.md` at the archive root.\n\n## Usage\n\nAsk your agent:\n\n```text\nAudit this repo for prompt debt and stale agent-facing context.\n```\n\nFor direct terminal usage, see Quick Start.\n\n## Design\n\n- `SKILL.md` is a short router.\n- `references/` contains judgment rules.\n- `lucid.py` is a thin CLI wrapper.\n- `action.yml` is experimental and not the primary CI surface.\n- `skills/lucid/scripts/lucid.py` performs deterministic checks.\n- `evals/fixtures` prevent regressions.\n- `.lucid/plan.md` is generated before any edit.\n\nMore detail: [docs/design-rationale.md](docs/design-rationale.md)\n\nProduct contract: [docs/product-design.md](docs/product-design.md)\n\nOutput schema: [docs/output-schema.md](docs/output-schema.md)\n\nPolicy packs: [docs/policy-packs.md](docs/policy-packs.md)\n\nGitHub Actions usage: [docs/github-actions.md](docs/github-actions.md)\n\nSecurity policy: [SECURITY.md](SECURITY.md)\n\nRelease checklist: [docs/release-checklist.md](docs/release-checklist.md)\n\n## Roadmap\n\nSee [docs/product-design.md](docs/product-design.md#roadmap) for the detailed\nroadmap.\n\n- v0.1: read-only scanner/planner\n- v0.2: skill packaging, CLI wrapper, basic scoring, terminal summaries,\n  diff-only suggestions, SARIF\n- v0.3: policy packs, config validation, source graph, provenance, redaction\n  preview metadata, migration target hints\n- v0.4: runtime compatibility docs, hosted package targets, usage boundaries\n- v1.0: stable schemas and optional CI recipes\n\n## Status\n\nLucid v0.4.0 is a public alpha. The current package is a read-only context\nhygiene scanner, planner, reporter, and review-only patch suggestion tool for\nlocal validation before applying cleanup changes.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdd3ok%2Flucid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdd3ok%2Flucid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdd3ok%2Flucid/lists"}