sphica 0.5.1 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/README.md +24 -28
- package/package.json +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
|
3
3
|
"name": "sphica",
|
|
4
|
-
"version": "0.5.
|
|
4
|
+
"version": "0.5.2",
|
|
5
5
|
"description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "iroha924",
|
package/README.md
CHANGED
|
@@ -11,17 +11,17 @@ English | [日本語](https://github.com/iroha924/sphica/blob/main/README.ja.md)
|
|
|
11
11
|
|
|
12
12
|
**Local memory of past implementation and decisions for Claude Code and Codex.**
|
|
13
13
|
Sphica records your coding sessions, and keeps what was decided, rejected, deferred, and built, each record quoting the words it came from.
|
|
14
|
-
Your agent finds those records when it searches, and sees the relevant ones on its own
|
|
14
|
+
Your agent finds those records when it searches, and sees the relevant ones on its own when it reads or edits a file they apply to (in Codex, before a shell command that names the file and before `apply_patch`).
|
|
15
15
|
The database is a single SQLite file on your machine.
|
|
16
16
|
|
|
17
17
|
## Features
|
|
18
18
|
|
|
19
19
|
- **Automatic recording.** Sphica keeps your prompts, the agent's final reply for each turn, and the paths of the files a turn changed (by the edit tools, or seen in `git status` at the turn's end).
|
|
20
20
|
- **Records with their sources.** `/sphica:trace` turns a session into records: decisions with the options rejected and why, constraints, implementations, findings, dead ends, and open questions. Every record quotes the exact words it came from, and a decision counts as adopted only when you said so.
|
|
21
|
-
- **Pull requests too.** `/sphica:harvest <number>` keeps a GitHub pull request (body, comments, reviews, review comments, commits, and
|
|
21
|
+
- **Pull requests too.** `/sphica:harvest <number>` keeps a GitHub pull request (body, comments, reviews, review comments, commits, and up to five issues the body says it closes) and records what it decided. A reviewer's suggestion stays a proposal unless the owner or a maintainer adopted it; a merge alone adopts nothing.
|
|
22
22
|
- **Evidence found later.** `/sphica:glean` adds evidence and corrections to existing records. It asks you for the source (an issue URL, the file and line, meeting notes) before saving; a claim without one is kept only as unsourced and never used as fact.
|
|
23
|
-
- **Shown when it matters
|
|
24
|
-
- **Search in Japanese and English.** Records
|
|
23
|
+
- **Shown when it matters.** At session start, the current work; before the agent reads or edits a file, or runs a shell command that names it, the decisions tied to that file; when your prompt names a recorded option or code symbol, that record. Works in both Claude Code and Codex.
|
|
24
|
+
- **Search in Japanese and English.** Records are made with search words in both languages, so a question in either language is more likely to find them.
|
|
25
25
|
- **Reviews check past decisions.** `/sphica:review` runs a reviewer per focus (correctness, security, written conventions, and past decisions by default; redundancy with `full`), and checks the diff against the records it touches.
|
|
26
26
|
|
|
27
27
|
Records are never rewritten: a correction is a new record that supersedes the old one, and the history stays.
|
|
@@ -60,7 +60,7 @@ codex plugin marketplace add iroha924/sphica --ref main
|
|
|
60
60
|
codex plugin add sphica@sphica
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
In Codex, open `/hooks` and mark Sphica's hooks as trusted.
|
|
63
|
+
In Codex, open `/hooks` and mark Sphica's hooks as trusted. Automatic recording does not start until you do. If a plugin update changes the hooks, trust them again.
|
|
64
64
|
|
|
65
65
|
**3. Set up in your repository**
|
|
66
66
|
|
|
@@ -81,7 +81,7 @@ sphica doctor
|
|
|
81
81
|
|
|
82
82
|
## Quick start
|
|
83
83
|
|
|
84
|
-
|
|
84
|
+
Only sessions in repositories you register (projects) go into Sphica's database; run `sphica init` in each one.
|
|
85
85
|
|
|
86
86
|
Work as usual. At the end of a session with something worth keeping, run `/sphica:trace` (`$sphica:trace` in Codex).
|
|
87
87
|
`/sphica:trace pending` lists earlier sessions not traced yet. To keep what a pull request decided, run `/sphica:harvest 123`.
|
|
@@ -100,20 +100,20 @@ Without being asked, Sphica adds a few past records to what the agent sees, each
|
|
|
100
100
|
- At session start: the current work and project-wide constraints.
|
|
101
101
|
- On a prompt that names a recorded code symbol, file path, or option.
|
|
102
102
|
- Before the agent reads or edits a file a decision applies to, and before a shell command that names such a file (naming it is not proof the command reads it). A read shows each record once per session.
|
|
103
|
-
- Before a review. When you run your own review command (any name containing `review`, or a name listed in the `SPHICA_REVIEW_COMMANDS`
|
|
104
|
-
environment variable, comma-separated), it gets the decisions your local change touches. `/sphica:review` checks them itself.
|
|
103
|
+
- Before a review (Claude Code only). When you run your own review command (any name containing `review`, or a name listed in the `SPHICA_REVIEW_COMMANDS`
|
|
104
|
+
environment variable, comma-separated), it gets the decisions your local change touches. `/sphica:review` checks them itself.
|
|
105
105
|
|
|
106
|
-
In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, and before a shell command that names such a file.
|
|
106
|
+
In Codex the same happens at session start, on a prompt, before an `apply_patch` edit, and before a shell command that names such a file (Codex reads files through shell commands, so this covers reads).
|
|
107
107
|
There is no review hook in Codex: run `$sphica:review`.
|
|
108
108
|
|
|
109
|
-
The agent searches with Sphica's `search` and opens full records with `read`. `status` tells it how much of the history has been traced, so an empty search is
|
|
109
|
+
The agent searches with Sphica's `search` and opens full records with `read`. `status` tells it how much of the history has been traced, so an empty search is less likely to be mistaken for "never decided".
|
|
110
110
|
|
|
111
111
|
## What gets recorded and where it goes
|
|
112
112
|
|
|
113
|
-
- **Where.** The database is `~/.sphica/sphica.db`.
|
|
114
|
-
- **What.** Your prompts, the agent's final reply for each turn, and the paths of changed files. Background-task notifications and messages from other agents are skipped when Sphica recognizes their format. Replies in the middle of a turn,
|
|
113
|
+
- **Where.** The database is `~/.sphica/sphica.db`. Captured sessions wait in a local queue, `~/.sphica/spool`, until they are written to it. Each machine has its own database; nothing is shared between machines.
|
|
114
|
+
- **What.** Your prompts, the agent's final reply for each turn, and the paths of changed files. Background-task notifications and messages from other agents are skipped when Sphica recognizes their format. Replies in the middle of a turn are not kept, nor are files created and deleted within one turn without the edit tools.
|
|
115
115
|
- **What was shown.** Each automatic delivery is logged by which records it showed, not their text.
|
|
116
|
-
- **Unregistered repositories.** Sessions in a repository you have not registered stay in the queue and are written after you register it. Held
|
|
116
|
+
- **Unregistered repositories.** Sessions in a repository you have not registered stay in the queue and are written after you register it. Held sessions are dropped after 30 days, and when more than 1,000 are waiting the oldest go first.
|
|
117
117
|
- **Secrets.** Only secrets with a recognizable shape are masked:
|
|
118
118
|
- keys with known prefixes
|
|
119
119
|
- `KEY=…` and `"password": …` assignments
|
|
@@ -123,20 +123,16 @@ The agent searches with Sphica's `search` and opens full records with `read`. `s
|
|
|
123
123
|
|
|
124
124
|
**Anything else is stored as typed, so do not paste secrets into a session.**
|
|
125
125
|
- **Network.** Sphica has no account, no hosted service, and no telemetry, and makes no network connections itself. `/sphica:harvest` and `/sphica:glean` run `gh api` with your credentials to read pull requests and issues, and `sphica doctor` runs `npm` and `claude` to check installed versions.
|
|
126
|
-
- **Text written by others.** Pull request and issue text may come from anyone. It is kept as a source and passed to the agent as data, never as instructions, and only the
|
|
126
|
+
- **Text written by others.** Pull request and issue text may come from anyone. It is kept as a source and passed to the agent as data, never as instructions, and only your words, or those of the repository's owner or a maintainer, can adopt a decision.
|
|
127
127
|
|
|
128
|
-
##
|
|
128
|
+
## What Sphica can't do yet
|
|
129
129
|
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
-
|
|
133
|
-
-
|
|
134
|
-
-
|
|
135
|
-
|
|
136
|
-
## Upgrading from 0.4
|
|
137
|
-
|
|
138
|
-
0.5.0 keeps records in a new format. A 0.4 database is refused and left unchanged; its records are not carried over.
|
|
139
|
-
Move `~/.sphica/sphica.db` aside (keep it if you want the old data), then run `sphica init` again in each repository.
|
|
130
|
+
- Only what you traced, harvested, or gleaned becomes a structured record. The rest of a conversation is searchable as captured text (`search` with `sources: true`).
|
|
131
|
+
- For shell commands, Sphica only sees whether a command names a file. It may show decisions for a file the command never reads, and a shell command that edits a file is not treated as an edit (in Codex, a patch passed to `apply_patch` through the shell is treated as an edit).
|
|
132
|
+
- Commands run through Claude Code's PowerShell tool (Windows without Git Bash) do not get decisions yet.
|
|
133
|
+
- In Codex, `$sphica:trace`, `$sphica:harvest`, and `$sphica:glean` can write only when Codex tells Sphica which directory the session is in. Current Codex does. When it does not, they write nothing and tell you why.
|
|
134
|
+
- Showing a record does not make the agent follow it.
|
|
135
|
+
- A code location in a record is checked against your working tree when it is read. Finding the code name (a function name, say) the record points to does not mean the decision still holds.
|
|
140
136
|
|
|
141
137
|
## Updating
|
|
142
138
|
|
|
@@ -200,11 +196,11 @@ Everything else runs inside Claude Code and Codex, through the `/sphica:*` comma
|
|
|
200
196
|
|
|
201
197
|
Report vulnerabilities privately as described in [SECURITY.md](https://github.com/iroha924/sphica/blob/main/SECURITY.md).
|
|
202
198
|
|
|
203
|
-
|
|
199
|
+
Each release is built by GitHub Actions from a tag on the head of a pull request whose CI has passed, and staged on npm.
|
|
204
200
|
The maintainer checks its SHA-512 checksum and provenance, then approves publication with two-factor authentication.
|
|
205
|
-
|
|
201
|
+
The [npm page](https://www.npmjs.com/package/sphica#provenance) links to the workflow and the commit each release was built from.
|
|
206
202
|
|
|
207
|
-
Dependabot opens pull requests to update the GitHub Actions used in CI
|
|
203
|
+
Dependabot opens weekly pull requests to update the GitHub Actions used in CI, and Renovate opens monthly ones for the npm dependencies bundled into the package.
|
|
208
204
|
|
|
209
205
|
## Contributing
|
|
210
206
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sphica",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.2",
|
|
4
4
|
"description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|