Context Docs helps your AI coding agent keep a short Markdown note in your project: what changed, why it was decided and what to do next. Start your next session by asking it to read that note.
CSV export is implemented. Two sample exports pass.Empty-input check not run yet: its sample input file is missing.
Decision
Keep the existing export API.Reason: current users are not affected.
Next step
Add the missing empty-input sample, then test it before calling the feature complete.
Next session “Read docs/context.md, then continue.”
A fictional CSV export handoff, not recorded agent output. You review what the agent writes.
01 One handoff, start to finish
Stop today. Know where to begin next time.
A fictional example: you spend a session adding CSV export to an app. Before you stop, your agent updates a short note in the project.
1 Today's session
You and your agent add CSV export
Two sample exports pass. The empty-input check cannot run yet because a sample input file is missing. You decide to keep the existing export API so current users are not affected.
2 Saved in docs/context.md
Current work
CSV export is implemented; empty-input behavior still needs testing.
Decision
Keep the existing export API to preserve compatibility.
Next step
Add the missing empty-input sample, then test it before calling the feature complete.
3 Your next session
You ask the agent to read the note
Instead of explaining everything again, you give it a starting point: the agreed API decision and the pending empty-input check. You review its plan and decide what happens next.
Illustrative and fictional, not recorded agent output. Your agent writes notes from your actual work, and you review the diff. Open the longer example
02 How it works
Three small habits. No new system.
Context Docs is two installable skills: reusable instructions for Codex or Claude Code. Your notes stay as ordinary Markdown that you can read and edit.
01
Set it up once
Install the skills, then run the setup skill in your project. It reuses your existing docs and adds a short maintenance rule to the instructions your agent loads. Check that the rule is actually loaded.
02
Review useful updates
The loaded rule guides the agent to update the note after meaningful work during active sessions. Review the diff like any other change. If an update is missed, ask for one.
03
Read the notes next time
Start a new session by asking the agent to read the saved file. A saved file alone does not make a new session read it.
Work, save what matters in project Markdown, then read it in the next session.
No background service, automatic memory or sync: the agent works only during your sessions, and you review what it writes. See the limits.
03 Get started
Set up once. Keep your usual workflow.
Install both skills, then run the setup skill inside the project you want to keep notes for.
Experimental · Released Core 0.2.7 · Adoption 0.1.16
These install commands select published v0.2.7: core 0.2.7 and adoption 0.1.16.
Already installed? Read the upgrade guidance before copying files. Preserve your local customizations.
Install in Codex
Paste this request into Codex:
Use $skill-installer to install both skills from jaredchu/context-docs
at the published tag v0.2.7:
- skills/context-docs
- skills/adopt-context-docs
Install them together in ~/.agents/skills/.
Preserve existing installations and local customizations; report version
mismatches before upgrading. Report the installed VERSION values:
context-docs 0.2.7 and adopt-context-docs 0.1.16.
Read this project's context entry point and its relevant linked documents.
Use the recorded decisions, current work and next steps to continue with the next task.
The context entry point is your project's starting document. Find its path in the README, documentation index, or the adoption marker'sEntry point: field.
Switching between Codex and Claude Code? The same saved files can carry unfinished work to the other client. See both directions.
Optional: release details and qualified checks (v0.2.4–v0.2.7)
The v0.2.7 release shortens repeated instructions while retaining the existing scope and safeguards. Guided checks in Codex and Claude cover refresh, repeat and re-adoption on one reused fixture. Codex's automatic-loading claim remains unverified; Claude instruction events support loading in those sessions only. These checks establish no general reliability or user-effort savings. Read the qualified simplification results. Everyday installs here select published v0.2.7.
The v0.2.4 release adds a small clarity preference during authorized context edits: use clear, direct sentences and consistent project terms while preserving conditions, uncertainty, rationale and evidence. Keep existing layouts and unrelated owner text. ASD-STE100 compliance is not required.
Both clients pass the focused Markdown checks. Claude's chat report adds an unsupported pronoun; the saved Markdown is unaffected. These guided, author-scored cases do not demonstrate comprehension gains or automatic everyday application. Read the qualified clarity smoke results.
The v0.2.5 release adds conditional guidance for concurrent sessions editing the same context file: agree on one writer before edits begin, send other participants' findings to that writer, and change writers through an explicit handoff. Prefer narrow edits; after a conflict or stale-text failure, reread the current file and reconcile changes before retrying. Installing skills in both Codex and Claude does not coordinate sessions. There is no file locking or automatic merge guarantee.
In the guided candidate smoke, both clients respect ownership and handoff and reread after the forced stale edit. Claude retries its own second mismatch without another reread, a procedural failure despite preserved final content. Codex corrects a read-only anchor-check error. These author-scored cases do not test simultaneous writers or establish general conflict prevention. Read the qualified concurrency smoke results.
The v0.2.6 release strengthens what gets saved: omit incidental personal metadata from shared additions, prefer repository-relative source links and summarize useful findings instead of repeating bookkeeping. Keep useful local paths and necessary diagnostic relationships in appropriate destinations. Preserve decisions, rationale, conditions, uncertainty and evidence. Review what you share; no automatic redaction or secret scanner is included.
Both clients pass visible saved-Markdown checks in the guided, author-scored smoke. Claude could not locate an unlinked private operator note with its restricted tools; filtering incoming content from that note remains untested. These cases establish no automatic everyday application or general privacy guarantee, and native journal capture was not tested. Read the qualified metadata-filtering smoke results.
04 Optional · Markdown progress
See the path. Find the blocker.
Your notes can include a small text diagram: the goal, what is done, what is blocked and what comes next. No web app or separate tracker.
Pilot CSV export [G] GOAL INCOMPLETE
|
|-- DONE CSV columns check [C]
|
`-- BLOCKED Empty-input check [E]
`-- NEEDS representative input [E]
`-- NEXT prepare input, then run empty-input check [E]
Outside the completion path:
PROPOSED five retries [G] (not approved or implemented)
Synthetic illustration, not a trial result or live project status. The checks are parallel; only the empty-input check needs the missing input.
Setup may start a view like this when your documented goal and work support one. Existing views keep their format and location, and the loaded rule guides updates during active sessions. To request or reshape a view explicitly:
Use context-docs to visualize this project's progress in Markdown.
Show the documented goal, completed and blocked work, meaningful advances
and next action as a compact visual path. Show dependencies and put blockers
beside the work they stop. Link to sources and mark unknowns. Reuse the
existing context layout, or link a separate Markdown file if that reads better.
Optional: qualified progress check (v0.2.3), including a strict write-scope failure
In the guided candidate smoke, progress checks pass in both clients. Codex also creates and removes a temporary hash file outside its allowed paths, so strict write scope fails. These author-scored cases do not establish general reliability. Read the qualified smoke evidence.
05 Deep dives
Want the details? Open an example.
Prefer something you can run? Try the Reading Queue example: a separate Cloudflare app with a step-by-step feature and context handoff walkthrough. All examples include handoffs between Codex and Claude Code.
Fictional work notes, the saved Markdown and the prompt for a fresh session.
Show the full demo
Illustrative, not an agent recording or evaluation result. These fictional notes show the intended workflow after adoption with the maintenance rule loaded. Review the Markdown diff; ask for an update if one is missed.
1. WORK NOTESFictional inputs
Goal: validate CSV export, including empty input, before calling it complete.
Maintainer-approved decision: keep the existing export API for compatibility.
Result: two sample export checks passed; full validation has not run.
Blocker: the empty-input fixture is missing, so that check cannot run yet.
Next action: add the empty-input fixture, then run that check.
2. SAVED CONTEXTdocs/context.md
Goal: validate CSV export, including empty input [S]
|-- DONE Two sample checks passed [S]
`-- BLOCKED Empty-input check: fixture missing [S]
`-- NEXT Add the fixture, then run the check [S]
Decision: keep the existing API for compatibility [S].
Limit: full validation has not run [S].
Source S: fictional work notes above. Real context links to its project decision and check records. Two sample passes do not mean the export is complete.
3. Resume in a fresh session
Read docs/context.md and its relevant linked sources.
Explain the next task and the decision we need to preserve. Do not edit yet.
Look for the missing fixture as the next task, the compatibility decision preserved and full validation still pending. This is the intended handoff, not an observed result. Use your project's actual context entry point.
Focused checks are guided and author-scored, with retained failures. Broad reliability, automatic everyday compliance and user-effort savings are not established. Read the evidence and limits.
Synthetic before and after
From scattered updates to a useful next step
The timeout changed from 10 to 20 seconds in configuration. Deployment is unverified. The approved database choice and restore-test blocker still matter.
Show the before and after
BEFOREcontext.md
# Example service context
The request timeout is 10 seconds.
Approved: keep SQLite for the pilot to avoid migration work (owner, September 1).
Proposed: evaluate PostgreSQL after the pilot.
September 2: still using SQLite.
September 3: confirmed that SQLite remains in use.
Restore testing is blocked on a representative synthetic dataset.
Next: prepare that dataset and run the restore procedure.
An old value and repeated diary entries obscure what matters.
AFTERThe same context.md
# Example service context
## Current state
As of September 26, the configured request timeout is 20 seconds
(`config/service.yaml`). Deployment of this change is unverified.
## Decisions
Approved: keep SQLite for the pilot to avoid migration work
(owner, September 1). Proposed: evaluate PostgreSQL after the pilot.
## Open work
Restore testing is blocked on a representative synthetic dataset.
Next: prepare that dataset and run the restore procedure.
The updated fact, its limits, the decision and the blocker stay together.
Synthetic illustration, not an evaluation result or a promise of token savings. Read the source example
06 Context with boundaries
Useful to the next reader. Appropriate for the project.
Keep it focused
The skill asks your agent to replace stale facts, consolidate repetition and link to detailed evidence. It does not need a transcript of every session.
Respect the destination
Keep shared project docs or choose local-only context excluded from Git. The agent checks tracking and ignore rules and keeps local content out of shared docs.
Keep control
You review ordinary Markdown changes. There is no background sync or automatic publishing. Optional event logging is separate from current context.
07 Do you need another tool?
Start with the workflow you already have.
Codex and Claude Code already provide instructions and memory, and both can maintain Markdown. Context Docs is an optional starting workflow for people without an established way to preserve project decisions, current work and handoffs. If your existing practice works, you may not need it.
Context Docs guides an agent during active sessions; it is not automatic memory, synchronization or a background service, and it does not guarantee accuracy, privacy, smaller documents or lower token usage. Review each diff, consequential claims and what you share.
Focused checks do not establish broad reliability, privacy guarantees or effort savings. Recorded studies do not yet establish effort savings for the intended users or a skill-specific correctness advantage. There is no automatic redaction, secret scanner, file locking or merge guarantee; when sessions share a context file, agree on one writer.
Daily use and concrete feedback help us find what needs improving.
