@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 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
- # Temporary Holding Version
1
+ # Locus
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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,3 @@
1
+ {
2
+ "contextFiles": { "include": [], "exclude": [] }
3
+ }
@@ -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.
@@ -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>