@granawkins/locus 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.md +127 -2
- package/bin/locus.js +239 -0
- package/package.json +27 -4
- package/settings.template.json +3 -0
- package/skills/locus/SKILL.md +43 -0
- package/system-prompt.md +37 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 granawkins
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,128 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Locus
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**The patron saint of a directory.**
|
|
4
|
+
|
|
5
|
+
One directory, one persistent agent, one cumulative conversation. Interactive
|
|
6
|
+
chats and headless commands continue the same history, with messages and
|
|
7
|
+
working artifacts kept in the directory. Locus stewards that work over time,
|
|
8
|
+
using Pi's built-in compaction while retaining JSONL history it can inspect.
|
|
9
|
+
|
|
10
|
+
Built on [Pi](https://pi.dev), Locus supports Pi's conversation CLI modes,
|
|
11
|
+
tools, skills, and [community extensions](https://pi.dev/packages). By default,
|
|
12
|
+
it inherits `AGENTS.md` instructions from the current directory and its
|
|
13
|
+
ancestors, and skills from `.agents/skills/` up to the repository root,
|
|
14
|
+
following Pi's project trust rules. Shared skills and native `.pi/`
|
|
15
|
+
configuration work normally.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npm install -g @granawkins/locus
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Requires Node.js 22.19+ on Linux, macOS, or Windows. Pi is included as a
|
|
24
|
+
dependency. On first use, run `locus` and use `/login` and `/model`
|
|
25
|
+
to connect a provider and select a model. On Windows, install Git for Windows
|
|
26
|
+
for Pi's default Bash tool, or select its PowerShell tool; see
|
|
27
|
+
[Pi on Windows](https://pi.dev/docs/latest/windows).
|
|
28
|
+
|
|
29
|
+
## Commands
|
|
30
|
+
|
|
31
|
+
Run Locus from the directory you want it to steward. It initializes automatically.
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
locus # Interactive conversation
|
|
35
|
+
locus "Audit your events" # Interactive, starting with this question
|
|
36
|
+
locus -p "Audit your events" # Run to completion and print the answer
|
|
37
|
+
locus -h # Help
|
|
38
|
+
locus --mode json "Audit events" # Stream Pi JSONL events
|
|
39
|
+
locus --mode rpc # Bidirectional Pi connection
|
|
40
|
+
locus install npm:pi-web-access # Install a shared community package
|
|
41
|
+
locus install -l npm:some-package # Install for the current Pi project
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Use `/reload` in an open chat after changing Pi resources or installing a package.
|
|
45
|
+
Project skills and extensions require Pi's project trust; unattended runs can
|
|
46
|
+
use already-saved trust or an explicit `--approve` decision.
|
|
47
|
+
|
|
48
|
+
## State
|
|
49
|
+
|
|
50
|
+
The first run creates `.locus/` in the current directory:
|
|
51
|
+
|
|
52
|
+
| File | Purpose |
|
|
53
|
+
|---|---|
|
|
54
|
+
| `settings.json` | This directory's Locus settings. |
|
|
55
|
+
| `session.jsonl` | Cumulative messages, tool results, and compaction records. |
|
|
56
|
+
| `lock` | Lock target; the active lock is maintained in `lock.lock/`. A competing run exits with code 75. |
|
|
57
|
+
|
|
58
|
+
Locks release on normal exit. After a forced termination, a stale lock becomes
|
|
59
|
+
recoverable after two minutes. The agent can keep notes and other working files in `.locus/`. Shared credentials,
|
|
60
|
+
settings, skills, and installed packages live in `~/.locus/agent/`; override that
|
|
61
|
+
location with `LOCUS_AGENT_DIR`. There is no shared master conversation.
|
|
62
|
+
|
|
63
|
+
## Settings
|
|
64
|
+
|
|
65
|
+
Global Pi settings live in `~/.locus/agent/settings.json` (or
|
|
66
|
+
`LOCUS_AGENT_DIR/settings.json`); Pi supports its full settings set there.
|
|
67
|
+
Each Locus directory has `.locus/settings.json`. Locus passes these local
|
|
68
|
+
settings to Pi using CLI options:
|
|
69
|
+
|
|
70
|
+
| Local field | Effect |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `defaultProvider`, `defaultModel`, `defaultThinkingLevel` | Choose the model and thinking level. A local provider needs a local or global model. |
|
|
73
|
+
| `enabledModels` | Scope available models. |
|
|
74
|
+
| `defaultTools` | Select or modify built-in tools; `[]` disables them. |
|
|
75
|
+
| `skills`, `extensions`, `prompts`, `themes` | Add resource paths. Local lists accept paths, not exclusion patterns or globs. |
|
|
76
|
+
| `theme`, `tuiMode` | Select the initial theme or terminal mode. |
|
|
77
|
+
| `contextFiles` | Include or exclude specific context files. |
|
|
78
|
+
|
|
79
|
+
`defaultTools` accepts either tool names or `+name`/`-name` modifiers; the two
|
|
80
|
+
forms cannot be mixed in one local list. An empty `enabledModels` list restores
|
|
81
|
+
all available models. Local resource paths resolve from the working directory.
|
|
82
|
+
|
|
83
|
+
Pi's other settings have no matching CLI option and are not supported in
|
|
84
|
+
`.locus/settings.json`; put them in the global file. Pi still reads its native
|
|
85
|
+
`.pi/settings.json` when present, subject to project trust. Explicit command
|
|
86
|
+
line options take precedence over Locus's local settings. Older local names
|
|
87
|
+
(`model`, `thinking`, `tools`, `customInstructions`, `preloadSkills`) remain
|
|
88
|
+
supported for existing directories; use Pi's names for new settings. Restart
|
|
89
|
+
Locus after editing settings. `system-prompt.md` defines the shared identity.
|
|
90
|
+
|
|
91
|
+
Locus reads `contextFiles.include` and `contextFiles.exclude` from both the
|
|
92
|
+
global Pi settings and local `.locus/settings.json`, combining the lists.
|
|
93
|
+
Relative global paths resolve from the agent directory; relative local paths
|
|
94
|
+
resolve from the working directory. `~/` and absolute paths also work.
|
|
95
|
+
|
|
96
|
+
When either `contextFiles` list is nonempty, Locus starts with Pi's normal
|
|
97
|
+
context-file discovery, removes excluded files, then adds included files even
|
|
98
|
+
outside that discovery path. Exclusion wins if a file appears in both lists;
|
|
99
|
+
symlinked paths are treated as the same file. Each path must name an existing
|
|
100
|
+
file. This setting does not filter other system-prompt additions. Skills are
|
|
101
|
+
unaffected. For example, a source agent can omit repository-wide instructions
|
|
102
|
+
while loading its own:
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"contextFiles": {
|
|
107
|
+
"include": ["/absolute/path/to/source/AGENTS.md"],
|
|
108
|
+
"exclude": ["/absolute/path/to/repo/AGENTS.md"]
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Use from another agent
|
|
114
|
+
|
|
115
|
+
Run `locus -p "task"` with the target directory as the working directory and
|
|
116
|
+
capture its answer and exit status. Invoke it again to continue. The included
|
|
117
|
+
[skill](skills/locus/SKILL.md) is a concise operating guide; copy its directory
|
|
118
|
+
into your harness's skills location to make it discoverable.
|
|
119
|
+
|
|
120
|
+
Limit concurrent jobs in the caller: Locus has no global queue. JSON mode emits
|
|
121
|
+
Pi events, not a validated result object; inspect errors and completion through
|
|
122
|
+
`agent_settled`. Database updates and completion evidence are task-specific.
|
|
123
|
+
Pi's session-switching commands can leave the canonical conversation during a
|
|
124
|
+
run; avoid them when maintaining one history. Tools use the invoking account's
|
|
125
|
+
permissions; a directory is not a sandbox.
|
|
126
|
+
|
|
127
|
+
MIT. [GitHub](https://github.com/granawkins/locus) ·
|
|
128
|
+
[Pi documentation](https://pi.dev/docs/latest) · `npm test`
|
package/bin/locus.js
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync, statSync } from 'node:fs';
|
|
3
|
+
import { dirname, join, resolve } from 'node:path';
|
|
4
|
+
import { homedir } from 'node:os';
|
|
5
|
+
import { spawn } from 'node:child_process';
|
|
6
|
+
import lockfile from 'proper-lockfile';
|
|
7
|
+
import { fileURLToPath } from 'node:url';
|
|
8
|
+
import { loadProjectContextFiles } from '@earendil-works/pi-coding-agent';
|
|
9
|
+
|
|
10
|
+
const template = new URL('../settings.template.json', import.meta.url);
|
|
11
|
+
|
|
12
|
+
function readObject(path) {
|
|
13
|
+
const value = JSON.parse(readFileSync(path, 'utf8'));
|
|
14
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error('expected an object');
|
|
15
|
+
return value;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function migrateSettings(state) {
|
|
19
|
+
const path = join(state, 'settings.json');
|
|
20
|
+
const legacy = join(state, 'config.json');
|
|
21
|
+
if (existsSync(path) || !existsSync(legacy)) return;
|
|
22
|
+
try {
|
|
23
|
+
const settings = readObject(legacy);
|
|
24
|
+
if ('systemPrompt' in settings) {
|
|
25
|
+
settings.customInstructions ??= settings.systemPrompt;
|
|
26
|
+
delete settings.systemPrompt;
|
|
27
|
+
}
|
|
28
|
+
writeFileSync(path, JSON.stringify(settings, null, 2) + '\n', { flag: 'wx' });
|
|
29
|
+
} catch (error) {
|
|
30
|
+
throw Error(`could not migrate .locus/config.json: ${error.message}`);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export function initialize(directory) {
|
|
35
|
+
const state = join(directory, '.locus');
|
|
36
|
+
mkdirSync(state, { recursive: true });
|
|
37
|
+
migrateSettings(state);
|
|
38
|
+
const settings = join(state, 'settings.json');
|
|
39
|
+
if (!existsSync(settings)) writeFileSync(settings, readFileSync(template), { flag: 'wx' });
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function contextArguments(directory, selections, agentDir) {
|
|
43
|
+
const include = [], exclude = [];
|
|
44
|
+
for (const { contextFiles, base } of selections) {
|
|
45
|
+
if (!contextFiles || typeof contextFiles !== 'object' || Array.isArray(contextFiles) ||
|
|
46
|
+
Object.keys(contextFiles).some(key => !['include', 'exclude'].includes(key))) {
|
|
47
|
+
throw Error('contextFiles must contain only include and exclude lists');
|
|
48
|
+
}
|
|
49
|
+
for (const [name, paths] of Object.entries({ include: contextFiles.include ?? [], exclude: contextFiles.exclude ?? [] })) {
|
|
50
|
+
if (!Array.isArray(paths) || paths.some(path => typeof path !== 'string' || !path.trim())) {
|
|
51
|
+
throw Error(`contextFiles.${name} must be a list of nonempty paths`);
|
|
52
|
+
}
|
|
53
|
+
(name === 'include' ? include : exclude).push(...paths.map(path => ({ path, base })));
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
if (!include.length && !exclude.length) return [];
|
|
57
|
+
|
|
58
|
+
const canonical = ({ path, base }) => {
|
|
59
|
+
const resolved = resolve(base, path.startsWith('~/') ? join(homedir(), path.slice(2)) : path);
|
|
60
|
+
try {
|
|
61
|
+
if (statSync(resolved).isFile()) return realpathSync(resolved);
|
|
62
|
+
} catch (error) {
|
|
63
|
+
if (error.code !== 'ENOENT') throw error;
|
|
64
|
+
}
|
|
65
|
+
throw Error(`context file is missing or not a regular file: ${resolved}`);
|
|
66
|
+
};
|
|
67
|
+
// Pi's CLI cannot filter individual context files, so select from Pi's own discovery.
|
|
68
|
+
const omitted = new Set(exclude.map(canonical));
|
|
69
|
+
const selected = new Map();
|
|
70
|
+
for (const file of loadProjectContextFiles({ cwd: directory, agentDir })) {
|
|
71
|
+
const identity = canonical({ path: file.path, base: directory });
|
|
72
|
+
if (!omitted.has(identity)) selected.set(identity, file.path);
|
|
73
|
+
}
|
|
74
|
+
for (const entry of include) {
|
|
75
|
+
const identity = canonical(entry);
|
|
76
|
+
if (!omitted.has(identity) && !selected.has(identity)) selected.set(identity, identity);
|
|
77
|
+
}
|
|
78
|
+
return ['--no-context-files', ...[...selected.values()].flatMap(path => ['--append-system-prompt', path])];
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export function profileArguments(directory, agentDir = process.env.LOCUS_AGENT_DIR || join(homedir(), '.locus', 'agent')) {
|
|
82
|
+
const state = join(directory, '.locus');
|
|
83
|
+
migrateSettings(state);
|
|
84
|
+
const settingsPath = join(state, 'settings.json');
|
|
85
|
+
const args = [];
|
|
86
|
+
try {
|
|
87
|
+
const selections = [];
|
|
88
|
+
const globalPath = join(agentDir, 'settings.json');
|
|
89
|
+
const global = existsSync(globalPath) ? readObject(globalPath) : {};
|
|
90
|
+
if ('contextFiles' in global) selections.push({ contextFiles: global.contextFiles, base: agentDir });
|
|
91
|
+
const profile = existsSync(settingsPath) ? readObject(settingsPath) : {};
|
|
92
|
+
const aliases = { model: 'defaultModel', thinking: 'defaultThinkingLevel', tools: 'defaultTools' };
|
|
93
|
+
for (const [oldName, newName] of Object.entries(aliases)) {
|
|
94
|
+
if (oldName in profile && newName in profile) throw Error(`${oldName} and ${newName} cannot both be set`);
|
|
95
|
+
}
|
|
96
|
+
const provider = profile.defaultProvider;
|
|
97
|
+
if (provider !== undefined && (typeof provider !== 'string' || !provider.trim())) {
|
|
98
|
+
throw Error('defaultProvider must be a nonempty string');
|
|
99
|
+
}
|
|
100
|
+
const localModel = profile.defaultModel ?? profile.model;
|
|
101
|
+
if (provider && !localModel && !global.defaultModel) {
|
|
102
|
+
throw Error('defaultProvider requires a defaultModel locally or globally');
|
|
103
|
+
}
|
|
104
|
+
for (const [rawKey, value] of Object.entries(profile)) {
|
|
105
|
+
const key = aliases[rawKey] ?? rawKey;
|
|
106
|
+
if (key === 'defaultProvider') {
|
|
107
|
+
args.push('--provider', value);
|
|
108
|
+
if (!localModel) args.push('--model', global.defaultModel);
|
|
109
|
+
} else if (['defaultModel', 'defaultThinkingLevel', 'customInstructions', 'theme', 'tuiMode'].includes(key)) {
|
|
110
|
+
if (typeof value !== 'string') throw Error(`${key} must be a string`);
|
|
111
|
+
if (value.trim()) args.push({ defaultModel: '--model', defaultThinkingLevel: '--thinking',
|
|
112
|
+
customInstructions: '--append-system-prompt', theme: '--use-theme', tuiMode: '--tui-mode' }[key], value);
|
|
113
|
+
} else if (key === 'contextFiles') {
|
|
114
|
+
selections.push({ contextFiles: value, base: directory });
|
|
115
|
+
} else if (['defaultTools', 'enabledModels', 'skills', 'extensions', 'prompts', 'themes', 'preloadSkills'].includes(key)) {
|
|
116
|
+
if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim())) {
|
|
117
|
+
throw Error(`${key} must be an array of nonempty strings`);
|
|
118
|
+
}
|
|
119
|
+
if (key === 'defaultTools') {
|
|
120
|
+
const modifiers = value.filter(item => /^[+-]/.test(item));
|
|
121
|
+
if (modifiers.length && modifiers.length !== value.length) {
|
|
122
|
+
throw Error('defaultTools cannot mix tool names and + or - modifiers in Locus settings');
|
|
123
|
+
}
|
|
124
|
+
if (value.length) args.push('--tools', value.join(','));
|
|
125
|
+
else if (rawKey !== 'tools') args.push('--no-builtin-tools');
|
|
126
|
+
} else if (key === 'enabledModels') {
|
|
127
|
+
args.push('--models', value.length ? value.join(',') : '*');
|
|
128
|
+
} else for (const entry of value) {
|
|
129
|
+
if (entry.startsWith('-') || entry.includes('*')) throw Error(`${key} supports paths only; use Pi settings for exclusions and globs`);
|
|
130
|
+
const resourcePath = entry.replace(/^\+/, '');
|
|
131
|
+
const resource = key === 'extensions' && resourcePath.startsWith('builtin:') ? resourcePath :
|
|
132
|
+
resolve(directory, resourcePath.startsWith('~/') ? join(homedir(), resourcePath.slice(2)) : resourcePath);
|
|
133
|
+
const option = { skills: '--skill', extensions: '--extension', prompts: '--prompt-template',
|
|
134
|
+
themes: '--theme', preloadSkills: '--skill' }[key];
|
|
135
|
+
args.push(option, resource);
|
|
136
|
+
if (key === 'preloadSkills') {
|
|
137
|
+
args.push('--append-system-prompt', `Preloaded skill: ${resource}\nResolve its relative references from ${dirname(resource)}.\n\n${readFileSync(resource, 'utf8')}`);
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
} else throw Error(`unknown field: ${key}`);
|
|
141
|
+
}
|
|
142
|
+
args.push(...contextArguments(directory, selections, agentDir));
|
|
143
|
+
} catch (error) {
|
|
144
|
+
throw Error(`invalid Locus settings: ${error.message}`);
|
|
145
|
+
}
|
|
146
|
+
return args;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
export async function launchPi(args, { directory, profileArgs = [], conversation = false } = {}) {
|
|
151
|
+
const entry = fileURLToPath(import.meta.resolve('@earendil-works/pi-coding-agent'));
|
|
152
|
+
const cli = join(dirname(entry), 'bundle', 'cli.js');
|
|
153
|
+
const env = {
|
|
154
|
+
...process.env,
|
|
155
|
+
PI_CODING_AGENT_DIR: process.env.LOCUS_AGENT_DIR || join(homedir(), '.locus', 'agent'),
|
|
156
|
+
};
|
|
157
|
+
let release = async () => {};
|
|
158
|
+
if (conversation) {
|
|
159
|
+
const state = join(directory, '.locus');
|
|
160
|
+
const target = join(state, 'lock');
|
|
161
|
+
writeFileSync(target, '', { flag: 'a' });
|
|
162
|
+
try {
|
|
163
|
+
release = await lockfile.lock(target, { stale: 120000, update: 10000, retries: 0 });
|
|
164
|
+
} catch (error) {
|
|
165
|
+
if (error.code !== 'ELOCKED') throw error;
|
|
166
|
+
console.error('locus: another process is using this directory.');
|
|
167
|
+
process.exitCode = 75;
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
170
|
+
const prompt = fileURLToPath(new URL('../system-prompt.md', import.meta.url));
|
|
171
|
+
const docs = `Installed Pi package: ${dirname(dirname(entry))}\nLocus package: ${fileURLToPath(new URL('../', import.meta.url))}`;
|
|
172
|
+
args = ['--session', join(state, 'session.jsonl'), '--session-dir', state,
|
|
173
|
+
'--system-prompt', prompt, '--append-system-prompt', docs, ...profileArgs, ...args];
|
|
174
|
+
}
|
|
175
|
+
const handlers = new Map();
|
|
176
|
+
try {
|
|
177
|
+
const child = spawn(process.execPath, [cli, ...args], { stdio: 'inherit', env });
|
|
178
|
+
for (const signal of process.platform === 'win32' ? ['SIGINT', 'SIGTERM'] : ['SIGINT', 'SIGTERM', 'SIGHUP']) {
|
|
179
|
+
const handler = () => child.kill(signal);
|
|
180
|
+
handlers.set(signal, handler);
|
|
181
|
+
process.on(signal, handler);
|
|
182
|
+
}
|
|
183
|
+
process.exitCode = await new Promise((resolve, reject) => {
|
|
184
|
+
child.once('error', reject);
|
|
185
|
+
child.once('close', (code, signal) => resolve(code ?? (signal === 'SIGINT' ? 130 : 143)));
|
|
186
|
+
});
|
|
187
|
+
} finally {
|
|
188
|
+
for (const [signal, handler] of handlers) process.off(signal, handler);
|
|
189
|
+
await release();
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
|
|
195
|
+
const help = `Usage:
|
|
196
|
+
locus init Create settings without starting a conversation (optional)
|
|
197
|
+
locus install <source> Install a Pi package into Locus
|
|
198
|
+
locus Open its persistent conversation
|
|
199
|
+
locus "Audit your events" Open chat with an initial message
|
|
200
|
+
locus -p "Audit your events" Run once and exit
|
|
201
|
+
locus --mode json "Audit" Stream Pi events and exit
|
|
202
|
+
locus --version Show the Locus version
|
|
203
|
+
|
|
204
|
+
Other arguments pass through to Pi. Use /login, /model, /settings, and
|
|
205
|
+
/reload inside chat. Skills and extensions use Pi's normal discovery.
|
|
206
|
+
Conversation commands initialize the current directory automatically.
|
|
207
|
+
Settings: ~/.locus/agent/settings.json and .locus/settings.json | History: .locus/session.jsonl
|
|
208
|
+
Requires Node.js 22.19 or newer on Linux, macOS, or Windows.`;
|
|
209
|
+
|
|
210
|
+
export async function main(args = process.argv.slice(2), directory = process.cwd()) {
|
|
211
|
+
if (args[0] === '--help' || args[0] === '-h') return console.log(help);
|
|
212
|
+
if (args[0] === '--version' || args[0] === '-v') return console.log(metadata.version);
|
|
213
|
+
if (args[0] === 'init') {
|
|
214
|
+
if (args.length !== 1) throw Error('usage: locus init');
|
|
215
|
+
initialize(directory);
|
|
216
|
+
return console.log('Initialized .locus/ (existing settings and history preserved).\nRun locus to start chatting.');
|
|
217
|
+
}
|
|
218
|
+
if (args[0] === 'install') return launchPi(args);
|
|
219
|
+
|
|
220
|
+
const sessionOptions = ['--session', '--session-dir', '--session-id', '--no-session',
|
|
221
|
+
'--continue', '-c', '--resume', '-r', '--fork'];
|
|
222
|
+
const separator = args.indexOf('--');
|
|
223
|
+
for (const arg of args.slice(0, separator < 0 ? args.length : separator)) {
|
|
224
|
+
if (sessionOptions.some(option => arg === option || arg.startsWith(`${option}=`))) {
|
|
225
|
+
throw Error('session-selection options are managed by Locus.');
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
initialize(directory);
|
|
229
|
+
return launchPi(args, { directory, profileArgs: profileArguments(directory), conversation: true });
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
233
|
+
try {
|
|
234
|
+
await main();
|
|
235
|
+
} catch (error) {
|
|
236
|
+
console.error(`locus: ${error.message}`);
|
|
237
|
+
process.exitCode = 1;
|
|
238
|
+
}
|
|
239
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,29 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@granawkins/locus",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "The patron saint of a directory: one persistent Pi conversation and its working files.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "granawkins",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/granawkins/locus.git"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/granawkins/locus#readme",
|
|
12
|
+
"bugs": { "url": "https://github.com/granawkins/locus/issues" },
|
|
13
|
+
"keywords": ["agent", "cli", "pi", "persistent", "agent-skills"],
|
|
14
|
+
"files": ["bin/", "skills/", "system-prompt.md", "settings.template.json"],
|
|
15
|
+
"publishConfig": { "access": "public" },
|
|
16
|
+
"type": "module",
|
|
17
|
+
"bin": { "locus": "bin/locus.js" },
|
|
18
|
+
"engines": { "node": ">=22.19.0" },
|
|
19
|
+
"os": ["linux", "darwin", "win32"],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"test": "node --test",
|
|
22
|
+
"prepack": "npm test"
|
|
23
|
+
},
|
|
24
|
+
"dependencies": {
|
|
25
|
+
"@earendil-works/pi-coding-agent": "1.4.0",
|
|
26
|
+
"proper-lockfile": "4.1.2"
|
|
27
|
+
},
|
|
28
|
+
"overrides": { "undici": "8.12.3" }
|
|
29
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: locus
|
|
3
|
+
description: Delegate recurring directory-owned work to a persistent directory agent through Locus, or continue work owned by an existing Locus agent.
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Locus
|
|
8
|
+
|
|
9
|
+
The patron saint of a directory: one persistent agent stewards its
|
|
10
|
+
work. Run commands in the target directory. Every invocation continues
|
|
11
|
+
`.locus/session.jsonl`; Pi compacts context while retaining inspectable history.
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
cd /path/to/item
|
|
15
|
+
locus -p "Audit this item, resolve the issues, verify the result, and save the report."
|
|
16
|
+
locus -p "Here is the missing detail. Continue."
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The first run initializes automatically. `-p` waits, prints the answer, and
|
|
20
|
+
exits. Capture stdout, stderr, and status; allow enough time for the task.
|
|
21
|
+
Specify the goal, authorized changes, verification, and result destination.
|
|
22
|
+
Database integrations and completion evidence are project-specific.
|
|
23
|
+
|
|
24
|
+
- Bound concurrency in the caller. One process per directory is allowed;
|
|
25
|
+
competing runs exit 75. Forced termination can leave a lock stale for two
|
|
26
|
+
minutes. There is no global queue.
|
|
27
|
+
- Global `~/.locus/agent/settings.json` (or `LOCUS_AGENT_DIR/settings.json`)
|
|
28
|
+
supports Pi's full settings set. Local `.locus/settings.json` supports model,
|
|
29
|
+
thinking, tool, resource, theme, and context-file options with Pi's field
|
|
30
|
+
names. Locus combines global and local `contextFiles` lists. Restart after
|
|
31
|
+
edits; never edit Pi's session files.
|
|
32
|
+
- Pi discovers ancestor `AGENTS.md` and `.agents/skills/` (skills stop at the
|
|
33
|
+
repository root). Project resources require trust; unattended jobs need
|
|
34
|
+
saved trust or an explicit authorized `--approve` decision.
|
|
35
|
+
- Shared setup lives in `~/.locus/agent/` or `LOCUS_AGENT_DIR`. Use `locus
|
|
36
|
+
install <source>` for Pi packages and `/reload` in an open chat. Login through
|
|
37
|
+
`/login` interactively; skills do not provide missing tools or credentials.
|
|
38
|
+
- JSON mode emits events, not a result schema. Inspect errors through
|
|
39
|
+
`agent_settled`; assistant failures may exit zero. RPC supports live dialogue.
|
|
40
|
+
|
|
41
|
+
Avoid Pi session-switching commands when preserving the canonical history.
|
|
42
|
+
A directory is not a sandbox. Inspect evidence before retrying interrupted
|
|
43
|
+
external actions, which may already have taken effect.
|
package/system-prompt.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
You are Locus, the patron saint and persistent steward of this directory. You run through Locus, a lightweight application built on Pi. Your identity is tied to this place and the work entrusted to you here.
|
|
2
|
+
|
|
3
|
+
<locus>
|
|
4
|
+
A Locus is a directory with one continuing agent conversation. The user may return to you directly in a terminal or invoke you through another program. Each invocation resumes this directory's saved conversation; the process need not remain running between tasks. Do not imply you are working or monitoring anything while you are not running.
|
|
5
|
+
|
|
6
|
+
Your responsibility is generally the items and work in the current directory. A directory might represent a venue whose events and fetcher you maintain, or a book whose text, audio, and supporting materials you produce. Learn the local purpose from the user's requests, existing files, and available instructions. Carry work forward across visits, preserving useful decisions and context.
|
|
7
|
+
</locus>
|
|
8
|
+
|
|
9
|
+
<continuity>
|
|
10
|
+
Your conversation is stored in .locus/session.jsonl within the current directory. Pi manages this transcript, including tool results and compaction. Older history can remain on disk even when it is no longer in your active context. You do not have perfect recall: when earlier details matter, search and read the relevant parts of your saved conversation using the available tools. Follow message and parent IDs when needed to distinguish the active conversation from other branches.
|
|
11
|
+
|
|
12
|
+
You may save notes, plans, research, intermediate results, scripts, and other working files inside .locus/. Choose clear names or subdirectories, such as .locus/notes/ and .locus/work/. Inspect existing files before writing. Leave session.jsonl, the lock file, and other Pi-managed session files to the harness; do not edit or overwrite them yourself. Put deliverables and source changes where the project and user expect them.
|
|
13
|
+
|
|
14
|
+
There is no shared master conversation across directories. Shared credentials, configuration, model cache, skills, and extensions normally live in ~/.locus/agent/; LOCUS_AGENT_DIR can override that location. Those shared resources are separate from this directory's conversation and working files.
|
|
15
|
+
</continuity>
|
|
16
|
+
|
|
17
|
+
<working_style>
|
|
18
|
+
- Act on the user's task using the tools and skills actually available in this invocation. Do not claim access to a tool or service merely because it is mentioned in these instructions.
|
|
19
|
+
- Read relevant local instructions, files, and skill guidance before making changes. Keep notes when they will help future work, without duplicating the entire transcript.
|
|
20
|
+
- You may inspect, create, and update files and code as needed for the task, including a directory's fetcher. Verify changes with checks appropriate to the work.
|
|
21
|
+
- Focus on this directory's responsibility. Access shared project resources or other locations when the task calls for it; the working directory is an organizational boundary, not a filesystem sandbox.
|
|
22
|
+
- Be concise and concrete. Report what you changed or learned, relevant checks, and anything unfinished or requiring the user's input.
|
|
23
|
+
- Use available search/list tools when enabled, or bash commands such as ls, rg, and find.
|
|
24
|
+
- Inspect PI_MODEL, PI_PROVIDER, and related session environment variables when asked which model or session is running rather than inferring that from your identity.
|
|
25
|
+
</working_style>
|
|
26
|
+
|
|
27
|
+
<docs>
|
|
28
|
+
Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
|
|
29
|
+
- Main documentation: README.md under the installed Pi package
|
|
30
|
+
- Additional docs: docs/ under the installed Pi package
|
|
31
|
+
- Examples: examples/ under the installed Pi package (extensions, custom tools, SDK)
|
|
32
|
+
- The runtime supplies the installed Pi package path. Resolve the documentation locations above from that path.
|
|
33
|
+
- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
|
|
34
|
+
- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md), MCP servers (docs/mcp.md), codemode scripts and non-LLM models such as classifiers and image models (docs/codemode.md)
|
|
35
|
+
- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
|
|
36
|
+
- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)
|
|
37
|
+
</docs>
|