Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# SHContext

SHContext is a repository context generator under development. It will create a `context/`
SHContext is a repository context generator under development. It creates a `context/`
directory that mirrors source folders and explains their responsibilities with
source references and explicit coverage limits.

The CLI implements local `scan <directory>` and `build <directory>` with one
OpenAI provider, incremental `update <directory>`, plus offline `verify <directory>`. Builds collect inspected evidence, summarize folders from leaves
The CLI implements local `scan <directory>`, active-host generation through
`prepare`/`submit`/`finalize`, optional OpenAI API `build`/`update`, and offline
`verify <directory>` and `query`. Builds collect inspected evidence, summarize folders from leaves
to root, add conservative relationships and publish a mirrored `context/` tree.
The reusable library exposes shared schemas, JS/TS analysis, generation and local
context querying. Four execution roles run sequentially by default; bounded folder
Expand All @@ -18,6 +19,15 @@ The current `0.1.0-alpha.1` candidate remains experimental. Start with the
offline walkthrough. See [evaluation methods and results](docs/benchmarks.md),
[organization freshness CI](docs/ci.md) and [release preparation](docs/release.md).

## Choose your environment

Start with [the step-by-step usage guides](docs/usage.md):

- [Claude Code terminal](docs/claude-code.md): local installation, first build, questions, changes, updates and recovery.
- [Claude web chat](docs/claude-web.md): four skill uploads, small source ZIPs, downloads and cross-chat updates.
- [Antigravity IDE](docs/antigravity.md): separate tool/source folders and an explicit local host-authoring workflow.
- [Claude Code on the web](docs/claude-code-cloud.md): cloud checkout/setup, distinct from ordinary Claude chat.

## Use uploaded repositories in Claude web

Build the web distribution with `npm run package:web -- /absolute/new/output`
Expand All @@ -27,13 +37,13 @@ enable code execution, and attach a source-only repository ZIP. Ask:
“Use context-web-build to generate context for frontend/src/lib/router from this
Headlamp archive and return a downloadable context ZIP.”
See [installation, runtime requirements and updates](docs/claude-web.md).
Actual Claude web account acceptance is [still pending](docs/claude-web-acceptance.md);
The bounded Claude web workflow has [actual account acceptance evidence](docs/claude-web-acceptance.md);
the CLI/plugin installation below is separate.

## Install the workflow plugin

Prepare the source checkout below, set its absolute path as `SHCONTEXT_HOME`, then
run these inside Claude Code after this change is merged:
run these inside Claude Code:

```text
/plugin marketplace add HarshPopat23/SHContext
Expand Down
210 changes: 210 additions & 0 deletions docs/antigravity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
# Antigravity IDE: generate context for a local repository

Use Antigravity's agent as the author and SHContext's local CLI as the scanner,
validator and publisher. This guide covers two separate local checkouts, such as
Headlamp and SHContext, already opened or accessible in Antigravity.

**Integration status:** SHContext ships a Claude Code plugin and Claude web
skills. It does not currently ship a dedicated Antigravity plugin or certify
Antigravity skill discovery. The supported building blocks here are the existing
host-mode commands. This is an explicit agent workflow, not a claim that the
Claude plugin's slash commands install into Antigravity. The local protocol is
exercised in tests; an actual Antigravity IDE session has not been acceptance-tested.

## 1. Check prerequisites and prepare the tool

You need an Antigravity account/model session with permitted local file and
terminal access, Git, Node 22.14+ on the 22 line or Node 24, and npm 10+.
The host account's normal allowance applies; no separate OpenAI generation key
is needed. Follow your organization's normal source-access settings.

Example folders: `/work/SHContext`, `/work/headlamp`, and a private session parent
`/work/shcontext-sessions`. Use your existing clones, or run in the IDE terminal:

```sh
cd /work
git clone https://github.com/HarshPopat23/SHContext.git
git clone https://github.com/kubernetes-sigs/headlamp.git
cd /work/SHContext
npm ci
node dist/cli/index.js --help
mkdir -p /work/shcontext-sessions
```

Do not install Headlamp's dependencies. In a Windows PowerShell terminal, use
`C:/work/...` paths and create the session parent with
`New-Item -ItemType Directory -Force C:/work/shcontext-sessions`.

## 2. Give the agent the correct paths

Open Headlamp in the IDE and make the SHContext checkout and session parent
accessible through the IDE's permitted workspace/file access. If access is denied,
use a dedicated parent workspace containing these checkouts or grant the required
folder access through the host UI. Do not work around an organization restriction.
Opening two folders does not automatically tell the agent which one to analyze.

Use these roles explicitly in prompts:

| Path | Role |
| ---------------------------------------- | ---------------------------------------- |
| `/work/SHContext` | Trusted tool and workflow documentation |
| `/work/headlamp/frontend/src/lib/router` | Selected source root |
| `/work/shcontext-sessions` | Existing parent for new private sessions |

The target is the router folder, so output belongs inside its `context/` directory.
A GUI-launched agent may not inherit variables exported in an IDE terminal.
Give absolute paths in the prompt; do not assume `SHCONTEXT_HOME` is available.

## 3. Select host mode with truthful provenance

Inspect the target's configuration and exclusions. If there is no
`shcontext.config.json`, create it in the selected router folder:

```json
{
"version": 1,
"provider": { "id": "host", "model": "antigravity-session" }
}
```

Keep other existing settings. If a provider already exists, deliberately decide
whether to migrate it rather than overwriting the file. The label identifies the
host workflow; it is not an authenticated model ID. Do not use `claude-code-session`
for analysis actually authored in Antigravity. Changing provider/model labels
invalidates previous generation, so keep the chosen label stable for updates.

Scan from the IDE terminal:

```sh
node "/work/SHContext/dist/cli/index.js" scan "/work/headlamp/frontend/src/lib/router"
```

Inspect coverage and skipped files. Selecting a subfolder does not inherit parent
configuration, ignore rules or source dependencies. Go and other unsupported
languages are inventory-only; choose an appropriate JS/TS scope first.

## 4. Ask the agent to perform the complete build

Paste this into Antigravity's agent chat with your actual paths:

```text
Generate SHContext context for this local repository folder.
Tool checkout: /work/SHContext
Selected source root: /work/headlamp/frontend/src/lib/router
Existing private session parent: /work/shcontext-sessions

Read /work/SHContext/docs/host-generation.md for the implemented host protocol.
You are the active Antigravity author: use provider id host and provenance label
antigravity-session, preserving existing settings. If a different provider is
configured, stop and report the required migration instead of silently replacing it.

Use a new session directory outside the selected source root. Run scan and
prepare. For each awaiting_draft request, read the full request and relevant
source, author a JSON response matching draft_schema, cite supplied evidence IDs,
and submit. Work sequentially from children to parents. Continue until ready,
then finalize and verify. Report output paths, coverage, accepted drafts and
uncertainty. Do not call a model API, run source/tests, install Headlamp
dependencies, edit final Markdown or commit generated output.
```

Do not send only “run shcontext build”: that command selects the optional API
workflow. Do not ask the agent to write final `CONTEXT.md` directly; it would omit
SHContext's validated publication/cache protocol.

The agent should execute commands equivalent to:

```sh
node "/work/SHContext/dist/cli/index.js" prepare "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-1"
```

`headlamp-router-1` must be new; its parent must exist. When status is
`awaiting_draft`, the agent reads the returned `request_file` and writes
`response.json` in that session. It must copy current session/request IDs and
cover every supplied direct source once. Then:

```sh
node "/work/SHContext/dist/cli/index.js" submit "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-1" --draft "/work/shcontext-sessions/headlamp-router-1/response.json"
```

Repeat for each new request. Once status is `ready`:

```sh
node "/work/SHContext/dist/cli/index.js" finalize "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-1"
node "/work/SHContext/dist/cli/index.js" verify "/work/headlamp/frontend/src/lib/router"
```

These commands validate but do not author the summaries: the Antigravity agent
must supply its own evidence-grounded drafts. The empty envelope illustration in
the protocol guide is not a valid finished draft. No parallel workers are required.

## 5. Read and query the result

Open `headlamp/frontend/src/lib/router/context/CONTEXT.md`. Keep the manifest,
report and cache in `context/.shcontext/`; they support future updates. Review
source citations and partial-coverage findings. Mechanical freshness is not proof
that every explanation is accurate or that any tests ran.

Ask the agent:

```text
Use /work/SHContext to query context for
/work/headlamp/frontend/src/lib/router: Where are route URLs created?
Run the local query operation, check freshness, read relevant current source
and cite paths/lines. Label outside-scope or unresolved relationships.
Do not regenerate context or edit files.
```

The underlying read-only command is:

```sh
node "/work/SHContext/dist/cli/index.js" query "Where are route URLs created?" --root "/work/headlamp/frontend/src/lib/router" --json
```

## 6. Refresh after an edit

After editing source, verify should report stale (exit 1 for a controlled change).
Ask the agent to use the same host label and root but a **new** session, for example
`/work/shcontext-sessions/headlamp-router-2`:

```text
Refresh existing SHContext context for /work/headlamp/frontend/src/lib/router.
Use /work/SHContext, provider host/model antigravity-session, and a new session
/work/shcontext-sessions/headlamp-router-2. Follow the host protocol with
prepare --update, author only requested drafts, submit, finalize and verify.
Report affected/regenerated/reused folders. Do not use the API update command,
change unrelated files or commit context.
```

The first command is:

```sh
node "/work/SHContext/dist/cli/index.js" prepare "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-2" --update
```

Submission/finalization use the same steps as the build, with the new session
path. An unchanged update can return `ready` immediately with zero new drafts;
it still needs finalize and verify. Preserve valid cached summaries rather than
rewriting them manually.

## 7. Failures and native skills

If the agent cannot access the tool/target, fix the allowed workspace paths first.
If Node or the built CLI is missing, prepare the trusted tool checkout. If the
host cannot execute commands or author the required JSON, this workflow is blocked;
plain prose summaries are not a validated SHContext result.

Exit 2 at finalization/verification means partial coverage; exit 1 means failure
or non-fresh verification. Inspect diagnostics. Interrupted sessions can resume
with the same root/session/mode when inputs remain unchanged. Source/config/output
changes require a new session. Preserve unknown output, locks and journals; never
delete them just to get a passing result. See [host recovery](host-generation.md).

Google documents workspace skills at `.agents/skills/<name>/SKILL.md` (legacy
`.agent/skills` also exists), with surface-specific global paths. That is the
host's discovery convention, not a declaration that SHContext ships an
Antigravity adapter. This guide deliberately uses explicit paths and the shared
protocol. Do not copy only Claude-specific SKILL.md files and assume their host
labels, slash namespaces or relative resources adapt automatically. See
[Google's skills reference](https://antigravity.google/docs/skills) and
[Google's skill-authoring codelab](https://codelabs.developers.google.com/getting-started-with-antigravity-skills)
if developing a separate host-specific skill later.
95 changes: 95 additions & 0 deletions docs/claude-code-cloud.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Claude Code on the web: use the cloud checkout

This means **claude.ai/code**, where Claude Code works in a cloud environment.
For ordinary Claude chat with attached ZIPs, use [the web chat guide](claude-web.md).
A path on your laptop is not a path inside the cloud environment.

Anthropic's [cloud guide][cloud] describes repository connection and environment
setup. Its [plugin installation guide][plugins] says cloud sessions do not load
plugins installed on your computer or those enabled only in repository settings.
This guide therefore uses SHContext's explicit host protocol, rather than claiming
that `/plugin install` or uploaded web skills configure a Code cloud session.
An actual SHContext cloud-session acceptance test has not been run.

## 1. Connect the repository

1. Open Claude Code on the web and use the host's onboarding to connect an
authorized repository, such as a Headlamp checkout/fork you can access.
2. Select the intended branch and cloud environment. Local unpushed edits may
not be present; inspect the actual checkout before generating context.
3. Confirm that the session has file/terminal access. Follow the organization's
normal policy for any setup downloads; do not assume unrestricted network.

This does not require attaching the ordinary-chat source ZIP. The cloud checkout
is the source input. Account access and normal Claude usage limits still apply.

## 2. Prepare SHContext in that environment

Ask the agent to report `pwd`, the absolute Headlamp checkout path,
`node --version`, `npm --version` and `git --version`. Require Node 22.14+ on the 22 line
or Node 24, with npm 10+. Do not guess `/work/headlamp` or your laptop's tool path.

Use the cloud environment's documented setup mechanism or permitted terminal
commands to clone a reviewed SHContext revision into a separate tool directory
and run `npm ci` there. GitHub/npm setup access is needed; if unavailable, report
that prerequisite instead of switching to an API or inventing an installed tool.
No Headlamp dependency install is needed. Do not store the tool inside the selected
router folder or a temporary plugin cache. Verify the built CLI with:

```sh
node /absolute/cloud/SHContext/dist/cli/index.js --help
```

Use actual reported paths, not these placeholders. Keep the reviewed tool revision
consistent across build/update sessions, or expect generator invalidation.

## 3. Generate with the active cloud session

Send this prompt after substituting the actual cloud paths:

```text
Use the SHContext host protocol in
/absolute/cloud/SHContext/docs/host-generation.md.
Tool checkout: /absolute/cloud/SHContext
Selected source root: /absolute/cloud/headlamp/frontend/src/lib/router
Private session parent: /absolute/cloud/shcontext-sessions

Create the session parent if missing and select a new child session outside
source. Use provider host and provenance label claude-code-cloud-session.
Preserve existing configuration; report before changing an existing provider.
Run scan, prepare, author each requested structured draft from inspected evidence,
submit sequentially, finalize and verify. Include references, coverage and
uncertainty. Do not install Headlamp dependencies, run source/tests or commit.
```

The model label is declared provenance, not a discovered exact model ID. This
uses the active Claude session; no separate OpenAI generation key is needed.
The command contract and accepted draft schema are the same as
[the local host protocol](host-generation.md). The selected router root receives
`context/CONTEXT.md` and its owned manifest/report/cache.

## 4. Ask, change, update and retain results

Ask the cloud agent to run `query "your question" --root <actual-root> --json`,
check freshness and inspect cited current source. For a standalone check use
`verify <actual-root>`. Neither command should silently regenerate context.
After an edit, request `prepare <actual-root> --session <new-outside-session>
--update`, then agent-authored drafts, submit, finalize and verify. Keep the same
host label and scope. An unchanged update should request zero new drafts.

Cloud files can outlive a command without being durable across environment resets.
Before ending, explicitly choose whether to download a full copy of `context/`
(including cache/manifest/report), or review and save it through your normal Git
branch/PR workflow. This guide does not authorize automatic commits or PRs in the
target repository. Private session state is not generated context to commit.
If the cloud environment expires, re-establish the tool/source paths and recover
only from state that actually remains. Do not claim a finished published result
from conversation history alone.

If runtime/setup access or account policy blocks execution, report the missing
prerequisite. If context is invalid/unowned, preserve it and inspect the error.
For expected stale/partial exits and session recovery, follow
[verification](verification.md) and [host generation](host-generation.md).

[cloud]: https://code.claude.com/docs/en/claude-code-on-the-web
[plugins]: https://code.claude.com/docs/en/plugins/install
Loading
Loading