agentic-home-cli 0.1.1 → 0.1.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.
Files changed (2) hide show
  1. package/README.md +33 -125
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,160 +4,68 @@ All your skills should live in one place.
4
4
 
5
5
  Coding harnesses scatter skills across `~/.claude`, `~/.cursor`, and other directories. This CLI brings them together in one shared folder and links each harness to it.
6
6
 
7
- **Requirements:** macOS or Linux, Python 3.11+, and Git for three-way text merges. No runtime Python dependencies, embedded LLM, network requests, or background service.
7
+ ## Get started
8
8
 
9
- ## Install and preview
10
-
11
- With npm (Node.js 18+):
9
+ Requires macOS or Linux, Node.js 18+, Python 3.11+, and Git for merges.
12
10
 
13
11
  ```sh
14
12
  npm install -g agentic-home-cli
15
- agentic sync --dry-run
13
+ agentic sync --dry-run # preview without changing files
14
+ agentic sync # import and link
16
15
  ```
17
16
 
18
- Or run `npx agentic-home-cli sync --dry-run`. Python 3.11+ must already be installed; npm does not install Python or Git. The launcher searches common Python executable names. Set `AGENTIC_PYTHON=/absolute/path/to/python3.12` to select an interpreter explicitly. Git is needed for three-way merges.
17
+ Or preview with `npx agentic-home-cli sync --dry-run`.
19
18
 
20
- From this checkout with pipx:
19
+ Files live in `~/.agentic/skills/` and `~/.agentic/AGENTS.md`. Choose another folder with `agentic sync --root PATH`; later commands remember it. Switching folders retains the old content.
21
20
 
22
- ```sh
23
- pipx install .
24
- agentic sync --dry-run
25
- agentic sync
26
- ```
21
+ Run `agentic sync` again to import new skills, merge changes, and repair missing links. Reload your coding tools afterward.
27
22
 
28
- The distribution is `agentic-home-cli`; the command is `agentic`. Check `command -v agentic` if you already have a command with that name.
23
+ ## Supported tools
29
24
 
30
- Without installing:
25
+ Only existing setups are linked.
31
26
 
32
- ```sh
33
- python3.12 -m agentic_cli.cli sync --dry-run --json
34
- ```
35
-
36
- Only existing agent setups are detected. Project files, credentials, sessions, caches, plugin installations, and unrelated settings are not managed. Skills can contain executable scripts and instructions: review their contents before sharing them with more agents. The CLI never executes skill content.
37
-
38
- ## Choose a directory
39
-
40
- ```sh
41
- agentic sync --root "$HOME/my shared agent files"
42
- agentic sync # remembers the selected directory
43
- agentic status
44
- ```
45
-
46
- The default is `~/.agentic`. The saved selection lives in `$XDG_CONFIG_HOME/agentic/config.json`, or `~/.config/agentic/config.json` when XDG_CONFIG_HOME is unset. `--root` overrides that selection. Relative paths become absolute; spaces are supported. Dry runs do not save a selection or modify the home.
47
-
48
- A root can already contain `skills/<name>/SKILL.md` and `AGENTS.md`. Other files in that root are left alone, including an existing `index.json`.
49
-
50
- To switch roots later, run `sync --root NEW_PATH`. The previous root becomes another import source, not an automatically preferred version. Old content is retained. Conflicts are resolved normally. A pending-root pointer routes `status`, `resolve`, and `continue` to the new workspace; the saved active root switches only once the transition is complete. Finish pending work before selecting another root. Nested/overlapping roots and roots within agent/configuration directories are rejected.
51
-
52
- ## Supported discovery locations
53
-
54
- | Agent detected | Skills destination | Shared instructions |
27
+ | Tool | Skills | Shared instructions |
55
28
  | --- | --- | --- |
56
- | `~/.claude` | `~/.claude/skills/<name>` | `~/.claude/CLAUDE.md` |
57
- | `~/.codex` | `~/.agents/skills/<name>` | `~/.codex/AGENTS.md` |
58
- | `~/.cursor` | `~/.cursor/skills/<name>` | Unsupported global file integration; reported explicitly |
59
- | `~/.pi/agent` | `~/.pi/agent/skills/<name>` | `~/.pi/agent/AGENTS.md` |
60
-
61
- Existing legacy `~/.codex/skills` entries are imported and linked too. Existing shared `~/.agents/skills` entries are imported when Codex or Pi is detected. Hidden catalogs such as `.system` are left untouched. Custom agent-home environment variables/settings are not interpreted in this first version.
62
-
63
- Portable skills are directories containing a regular `SKILL.md` file (a directory with that name is invalid). Pi-only standalone Markdown skills are reported and left untouched, rather than made undiscoverable by other agents. Instructions have one shared body, without agent-specific additions.
64
-
65
- Cursor's documented global User Rules are configured in Settings, not discovered from a documented global file path. The CLI therefore does **not** create a misleading `~/.cursor/rules` wrapper or modify Cursor's database. A thin wrapper/reference is permitted if a supported global hook becomes available; it must reference the selected root rather than hardcode `~/.agentic`.
66
-
67
- `AGENTS.override.md` in Codex or Pi blocks instruction publication and is reported for explicit reconciliation. It does not stop unrelated skills. Additional custom instruction settings and project-local instructions remain outside this tool's scope.
29
+ | Claude Code | `~/.claude/skills` | `~/.claude/CLAUDE.md` |
30
+ | Codex | `~/.agents/skills` | `~/.codex/AGENTS.md` |
31
+ | Cursor | `~/.cursor/skills` | Not supported |
32
+ | Pi | `~/.pi/agent/skills` | `~/.pi/agent/AGENTS.md` |
68
33
 
69
- ### Discovery evidence
34
+ Existing `~/.codex/skills` entries are imported too. Skills need a regular `SKILL.md` file. Hidden catalogs, standalone Markdown skills, custom agent locations, and Cowork aren't managed. Cursor's global instructions stay in Settings.
70
35
 
71
- Checked against primary documentation during implementation:
36
+ ## Resolve conflicts
72
37
 
73
- - [Claude Code skills](https://code.claude.com/docs/en/skills): personal `~/.claude/skills/<name>/SKILL.md`.
74
- - [Claude Code memory](https://code.claude.com/docs/en/memory): user `~/.claude/CLAUDE.md`. Cowork has additional symlink/import restrictions and is **not** a supported target.
75
- - [Codex skills](https://developers.openai.com/codex/skills/): user `~/.agents/skills`; symlinked skill folders explicitly supported.
76
- - [Codex instructions](https://developers.openai.com/codex/guides/agents-md/): global `~/.codex/AGENTS.md`, with `AGENTS.override.md` taking precedence.
77
- - [Cursor skills](https://cursor.com/docs/context/skills): global `~/.cursor/skills` and compatibility discovery locations.
78
- - [Cursor rules](https://cursor.com/docs/context/rules): `.cursor/rules` is project-scoped; global User Rules live in Settings.
79
- - [Pi README](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md#context-files) and [skills documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md): global `~/.pi/agent/AGENTS.md`, skill catalogs, and override behavior. Also verified against the locally installed Pi documentation.
80
-
81
- These are documented discovery contracts, not a claim of live end-to-end validation in each agent application. Restart/reload your agents and inspect their loaded skills/instructions after setup.
82
-
83
- ## Conflicts, like Git
38
+ Matching content combines. Conflicting content needs your choice; no tool takes priority. Unaffected skills sync while conflicting originals stay in place.
84
39
 
85
40
  ```sh
86
- agentic sync
87
- agentic status --json
41
+ agentic status
88
42
  agentic resolve CONFLICT_ID --take claude
89
43
  agentic continue
90
44
  ```
91
45
 
92
- There is **no source precedence**. Identical content deduplicates; unique files combine. First-import differences without a recorded common ancestor become conflicts. Subsequent text changes use `git merge-file` when a baseline exists. Multiple distinct variants, binary differences, and type collisions are never guessed away.
93
-
94
- Non-conflicting skills are organized immediately. An entire conflicting skill remains inactive in the new home until its files are resolved; the agents keep their original files. Shared instructions are a separate activation unit. Conflict-marked files live only in private working copies, never in active discovery locations.
95
-
96
- In a terminal, the CLI offers a source label, an edited file/directory, or deferral. For manual or LLM editing:
97
-
98
- ```sh
99
- agentic sync --json
100
- # Inspect conflicts[].variants and conflicts[].working_copy.
101
- # Edit the working copy; for a skill, preserve the entire directory tree.
102
- agentic resolve CONFLICT_ID --file '/reported/working/copy'
103
- agentic continue --json
104
- ```
105
-
106
- `resolve` stages a snapshot, so edit first and stage afterward. `continue` validates the resolved node type and rediscovers sources, including agents and legacy catalogs added since staging. New or changed sources invalidate the staged result and refresh the conflict workspace; previously unseen content is never silently selected against. An instruction override that appears meanwhile also blocks publication. Repeated `sync` calls retain unfinished working copies.
107
-
108
- Conflict markers beginning with `<<<<<<<`, `=======`, or `>>>>>>>` are rejected anywhere in staged text. Binary files require explicit source selection or replacement content. If documentation intentionally contains lines with these prefixes, rewrite/indent those lines before staging.
46
+ Or edit the reported working copy, then use `--file PATH` instead of `--take claude`. Stage edits before continuing. New or changed sources require another review. Remove conflict markers before staging.
109
47
 
110
- **LLM contract:** use `--json` to avoid prompts; stable conflict IDs, labeled live source paths, snapshot locations, relative conflicting paths, and resolution commands are returned. No PTY is required. Exit codes: `0` success, `1` operational failure, `2` unresolved conflicts or blocked units. JSON goes to stdout; normal human diagnostics go to stderr. `--dry-run` uses the publication validation path and reports prospective conflicts, invalid units, and catalog normalization without creating workspaces.
48
+ Add `--json` for scripts or agents: no prompts; exit codes are `0` for success, `1` for errors, and `2` for conflicts or blocked files.
111
49
 
112
- ## Repeated runs and symlinks
50
+ ## Before you sync
113
51
 
114
- - New skills and regular files that replace managed links are imported through the same workflow.
115
- - Missing discovery links are repaired when the canonical content exists.
116
- - Absence is not a deletion instruction. Missing children retained in a baseline are restored; missing whole units with no live source are reported instead of silently recreated. Deletion propagation is intentionally unsupported.
117
- - Valid external source links are retained when the selected content matches. Their targets are not moved or modified. When a merge requires a local copy, content is materialized; nested source links are followed into that copy, not rewritten in the external source.
118
- - Whole-catalog links to the selected canonical catalog can remain as-is. Other whole-catalog links are backed up and replaced by a local catalog of child links before individual skills are adopted. External targets remain untouched.
119
- - Broken links, cycles, special files, and unsafe directory-link writes are reported. A missing/invalid unit does not normally block independent units.
120
- - An unchanged successful rerun does not rewrite content, links, configuration, or backups.
52
+ - Review skills before sharing them. The CLI doesn't execute their contents.
53
+ - Project files, credentials, and unrelated settings stay untouched.
54
+ - Deletions don't propagate. Missing files may be restored from the saved baseline.
55
+ - `AGENTS.override.md` in Codex or Pi blocks shared instructions until you reconcile it.
56
+ - Backups and conflict copies stay in `<root>/.agentic/`. Backups preserve content, ordinary permissions, and symlink text, but not extended metadata. Restoration is manual; there is no undo command or automatic pruning.
57
+ - Interrupted writes resume on the next mutating command. Recovery refuses newer edits; changes across directories aren't one atomic operation.
121
58
 
122
- ## Backups and recovery
59
+ ## Troubleshooting and development
123
60
 
124
- Private state lives under `<root>/.agentic/`:
61
+ If Python isn't found, set `AGENTIC_PYTHON` to a Python 3.11+ executable. Check `command -v agentic` if another CLI uses that name.
125
62
 
126
- ```text
127
- state.json ownership, baselines, pending resolutions/publication
128
- journal.json one interrupted filesystem replacement (when present)
129
- conflicts/<id>/... retained source variants and editable working copies
130
- backups/<uuid>.json original path plus lossless snapshot before replacement
131
- ```
132
-
133
- Snapshots preserve bytes (base64), ordinary POSIX permissions, directory entries, and original symlink text. They do not preserve ACLs, extended attributes, ownership, timestamps, or hard-link relationships. Full snapshots favor simplicity over storage efficiency; backups are never automatically pruned.
134
-
135
- A process lock prevents concurrent writers through the same configuration directory. Journaled publication resumes on the next mutating command. File/link replacement is atomic where POSIX allows it. Replacing nonempty directories or changing between directory and non-directory types has a brief recoverable gap; the tool does not claim a cross-directory filesystem transaction. Recovery refuses to overwrite newer changes.
136
-
137
- Manual restore: inspect a backup's `path` first, then reconstruct it into a **new scratch path**, not over live files:
138
-
139
- ```sh
140
- python3.12 - /absolute/backup.json /absolute/new-scratch-path <<'PY'
141
- import json, sys
142
- from pathlib import Path
143
- from agentic_cli.storage import exists, materialize
144
- record = json.loads(Path(sys.argv[1]).read_text())
145
- target = Path(sys.argv[2])
146
- assert not exists(target), 'Choose a new scratch path'
147
- assert record['original'] is not None, 'There was no original at this path'
148
- materialize(target, record['original'])
149
- print('Original location:', record['path'])
150
- print('Restored snapshot:', target)
151
- PY
152
- ```
153
-
154
- Run this from the checkout with a compatible Python, or from an environment with the package installed. Review the result before manually replacing the live path. A restored relative symlink keeps its original text and may only resolve correctly at its original location. The CLI intentionally has no undo/delete-backups command. Its private state is trusted local data; do not edit journals or accept them from untrusted sources.
155
-
156
- ## Development checks
63
+ From a checkout:
157
64
 
158
65
  ```sh
66
+ pipx install .
67
+ npm test
159
68
  python3.12 -m unittest discover -s tests -v
160
- python3.12 -m pip wheel --no-deps . --wheel-dir /tmp/agentic-wheels
161
69
  ```
162
70
 
163
- Tests use temporary homes, including subprocess CLI tests. They never run `sync` against the developer's real home. CI is configured to run the suite and package installation on macOS/Linux with Python 3.11 and 3.12. No test framework dependency is needed.
71
+ Tests use temporary homes. Discovery paths follow tool documentation; loading in each application hasn't been tested end to end.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-home-cli",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "All your skills should live in one place. Coding harnesses scatter skills across ~/.claude, ~/.cursor, and other directories. This CLI brings them together in one shared folder and links each harness to it.",
5
5
  "license": "UNLICENSED",
6
6
  "bin": { "agentic": "bin/agentic.cjs" },