Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Use friendly numbered agent and harness defaults

deea147cb26bfc3
diff --git a/cli/src/lib/projectFolder.spec.ts b/cli/src/lib/projectFolder.spec.ts
index 44587739d..77a3e688a 100644
--- a/cli/src/lib/projectFolder.spec.ts
+++ b/cli/src/lib/projectFolder.spec.ts
@@ -24,10 +24,17 @@ describe('project folder preparation', () => {
it('creates different folders for two deliberate new projects', async () => {
const folders = await Promise.all([prepareProjectFolder({ source: 'new' }, { root }), prepareProjectFolder({ source: 'new' }, { root })])
expect(new Set(folders).size).toBe(2)
- expect(folders.every(folder => folder.startsWith(join(root, 'project-')))).toBe(true)
+ expect(new Set(folders)).toEqual(new Set([join(root, 'agent-1'), join(root, 'agent-2')]))
expect(await readdir(root)).toHaveLength(2)
})
+ it('continues numbering past existing folders and files without changing them', async () => {
+ await mkdir(join(root, 'agent-2'))
+ await writeFile(join(root, 'agent-4'), 'keep')
+ expect(await prepareProjectFolder({ source: 'new' }, { root })).toBe(join(root, 'agent-5'))
+ expect(await readFile(join(root, 'agent-4'), 'utf8')).toBe('keep')
+ })
+
it('publishes a complete clone and never replaces existing files or starts a second clone', async () => {
const project = parseProjectFolder({ projectSource: 'remote', repositoryUrl: 'owner/repo' })!
const clone = vi.fn(async (url: string, destination: string) => {
diff --git a/cli/src/lib/projectFolder.ts b/cli/src/lib/projectFolder.ts
index 6f46c240b..e0955dbbc 100644
--- a/cli/src/lib/projectFolder.ts
+++ b/cli/src/lib/projectFolder.ts
@@ -1,5 +1,5 @@
import { spawn } from 'node:child_process'
-import { lstat, mkdir, mkdtemp, rename, rm } from 'node:fs/promises'
+import { lstat, mkdir, mkdtemp, readdir, rename, rm } from 'node:fs/promises'
import { homedir } from 'node:os'
import { join } from 'node:path'
@@ -48,11 +48,23 @@ export async function prepareProjectFolder(
project: ProjectFolder,
options: { root?: string; clone?: (url: string, destination: string) => Promise<void> } = {},
): Promise<string> {
- const root = options.root ?? join(homedir(), 'Harness Projects')
+ const root = options.root ?? join(homedir(), 'harnesses')
let staging: string | undefined
try {
await mkdir(root, { recursive: true })
- if (project.source === 'new') return await mkdtemp(join(root, 'project-'))
+ if (project.source === 'new') {
+ const numbers = (await readdir(root)).map(name => /^agent-([1-9]\d*)$/.exec(name)?.[1])
+ let next = numbers.reduce((max, value) => value && BigInt(value) > max ? BigInt(value) : max, 0n) + 1n
+ for (;;) {
+ const folder = join(root, `agent-${next++}`)
+ try { await mkdir(folder); return folder }
+ catch (error) {
+ // mkdir reserves the name atomically, including simultaneous desktop
+ // and remote creates. Files and symlinks also count as occupied.
+ if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+ }
+ }
+ }
const destination = join(root, project.name)
if (await exists(destination)) throw new ProjectFolderError('PROJECT_EXISTS', `“${project.name}” already exists. Choose Local to open that folder.`)
staging = await mkdtemp(join(root, '.harness-clone-'))
diff --git a/cli/src/lib/registry.spec.ts b/cli/src/lib/registry.spec.ts
index 2d3fa11d8..f96e9bb69 100644
--- a/cli/src/lib/registry.spec.ts
+++ b/cli/src/lib/registry.spec.ts
@@ -1024,6 +1024,27 @@ describe('agent identity: the process owns the agent, the session is bound to it
expect(registry.list()).toHaveLength(1)
})
+ it('gives new agents stable numbered names across binding and reload without changing custom names', async () => {
+ const { registry } = await loadRegistryModule()
+ registry.load()
+ const first = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%7' }], cwd: '/tmp/demo' })!
+ const second = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%8' }], cwd: '/tmp/demo' })!
+ expect(registry.displayName(first)).toBe('agent-1')
+ expect(registry.displayName(second)).toBe('agent-2')
+ const bound = registry.register({ engine: 'opencode', sessionId: 'session-numbered', tmuxPane: '%7', title: 'OC | Greeting' })!.entry
+ expect(registry.displayName(bound)).toBe('agent-1')
+ registry.rename(second.agentId, 'My project')
+ const { registry: reloaded } = await loadRegistryModule()
+ reloaded.load()
+ expect(reloaded.displayName(reloaded.byAgent(first.agentId)!)).toBe('agent-1')
+ expect(reloaded.displayName(reloaded.byAgent(second.agentId)!)).toBe('My project')
+ const third = reloaded.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%9' }], cwd: '/tmp/demo' })!
+ expect(reloaded.displayName(third)).toBe('agent-3')
+ reloaded.rename(third.agentId, 'agent-10')
+ const fourth = reloaded.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%10' }], cwd: '/tmp/demo' })!
+ expect(reloaded.displayName(fourth)).toBe('agent-11')
+ })
+
it('persists a failed launch for reconnect while keeping its terminal route', async () => {
const { registry } = await loadRegistryModule()
registry.load()
diff --git a/cli/src/lib/registry.ts b/cli/src/lib/registry.ts
index aba34e4d8..307f8e9c8 100644
--- a/cli/src/lib/registry.ts
+++ b/cli/src/lib/registry.ts
@@ -129,6 +129,8 @@ export interface RegisteredSession {
launcherId?: string
transcriptPath: string | null
projectDir: string
+ /** Stable default for agents created by Harness; discovered agents keep their existing names. */
+ defaultName?: string
cwd: string | null
/** Authoritative backend-neutral terminal placements for this one process-owned agent. */
runtimes: TerminalRuntimeRef[]
@@ -168,11 +170,10 @@ export interface RegisterInput {
}
/** Display name for a session's "project" tab/tile. A user rename (persisted override) is
- * authoritative and FIXED — it must NOT drift back to the tmux pane title, which Claude keeps
- * rewriting to the latest convo topic. Only a session the user never renamed auto-follows the title,
- * then falls back to "<folder> · <id4>". */
+ * authoritative and FIXED. Harness-created agents start with a numbered name;
+ * discovered sessions retain their title/folder fallback. */
export function projectDisplayName(s: RegisteredSession): string {
- return NAME_OVERRIDES.get(s.sessionId) || NAME_OVERRIDES.get(s.agentId) || titleDisplayName(s.title) || defaultProjectDisplayName(s)
+ return NAME_OVERRIDES.get(s.sessionId) || NAME_OVERRIDES.get(s.agentId) || s.defaultName || titleDisplayName(s.title) || defaultProjectDisplayName(s)
}
const FILE = join(env.ADAPTER_DATA_DIR, 'registry.json')
@@ -371,6 +372,8 @@ function strictPersistedRow(value: unknown): RegisteredSession | null {
engine: row.engine as AgentEngine,
transcriptPath: typeof row.transcriptPath === 'string' ? row.transcriptPath : null,
projectDir: row.projectDir,
+ defaultName: typeof row.defaultName === 'string' && /^agent-[1-9]\d*$/.test(row.defaultName)
+ ? row.defaultName : undefined,
cwd: typeof row.cwd === 'string' ? row.cwd : null,
runtimes,
primaryRuntimeKey: normalizedPrimary,
@@ -751,6 +754,8 @@ class Registry {
...(rawGridLaunch !== undefined ? { gridLaunch: rawGridLaunch } : {}),
...(raw.bypassPermission === true ? { bypassPermission: true } : {}),
transcriptPath,
+ defaultName: typeof raw.defaultName === 'string' && /^agent-[1-9]\d*$/.test(raw.defaultName)
+ ? raw.defaultName : undefined,
title: titleDisplayName(typeof raw.title === 'string' ? raw.title : null),
sessionId: bound ? rawSessionId : '',
projectDir: !repairedCodexTranscript && typeof raw.projectDir === 'string' && raw.projectDir
@@ -975,6 +980,7 @@ class Registry {
schemaVersion: 2,
active: true,
launch: { state: 'starting' },
+ defaultName: this.nextAgentName(),
agentId,
sessionId: '',
boundAt: null,
@@ -1006,6 +1012,19 @@ class Registry {
return entry
}
+ private nextAgentName(): string {
+ let next = 1n
+ const names = [
+ ...this.list().flatMap(agent => [agent.defaultName, projectDisplayName(agent)]),
+ ...NAME_OVERRIDES.values(),
+ ]
+ for (const name of names) {
+ const match = name && /^agent-([1-9]\d*)$/.exec(name)
+ if (match && BigInt(match[1]!) >= next) next = BigInt(match[1]!) + 1n
+ }
+ return `agent-${next}`
+ }
+
/** Discovered process agents that have no engine session bound yet. */
unbound(): RegisteredSession[] {
return this.list().filter((s) => !s.sessionId)
@@ -1129,6 +1148,7 @@ class Registry {
grid: existing?.grid ?? null,
// The credential-bearing launch. Like codexHome: written once, carried forward, never re-derived.
gridLaunch: existing?.gridLaunch ?? null,
+ defaultName: existing?.defaultName,
transcriptPath: effectiveTranscriptPath,
projectDir: engine === 'grok' || engine === 'agy' || engine === 'copilot'
? basename(input.cwd ?? existing?.cwd ?? '') || sessionId
diff --git a/desktop/lib/core/project_folder.dart b/desktop/lib/core/project_folder.dart
index 460bc7ba9..8a1801518 100644
--- a/desktop/lib/core/project_folder.dart
+++ b/desktop/lib/core/project_folder.dart
@@ -29,7 +29,7 @@ class ProjectFolderRequest {
'Could not find your home folder. Choose Local to select a folder.',
);
}
- final root = Directory(projectHome ?? p.join(home!, 'Harness Projects'));
+ final root = Directory(projectHome ?? p.join(home!, 'harnesses'));
try {
await root.create(recursive: true);
if (repository case final repo?) {
@@ -38,13 +38,35 @@ class ProjectFolderRequest {
root.path,
);
}
- // The OS reserves a unique folder atomically. No name prompt or existing
- // project is needed, and two deliberate creations cannot share a folder.
- return (await root.createTemp('project-')).path;
+ var next = BigInt.one;
+ await for (final entry in root.list(followLinks: false)) {
+ final match = RegExp(r'^agent-([1-9]\d*)$')
+ .firstMatch(p.basename(entry.path));
+ if (match == null) continue;
+ final number = BigInt.parse(match.group(1)!);
+ if (number >= next) next = number + BigInt.one;
+ }
+ for (;;) {
+ final folder = p.join(root.path, 'agent-$next');
+ next += BigInt.one;
+ // Directory.create accepts an existing directory. The platform mkdir
+ // command reserves it exclusively, so concurrent creates never share
+ // a workspace. Paths are arguments, never shell text.
+ final result = await Process.run('mkdir', [folder]);
+ if (result.exitCode == 0) return folder;
+ if (await FileSystemEntity.type(folder, followLinks: false) ==
+ FileSystemEntityType.notFound) {
+ throw FileSystemException('Could not create folder', folder);
+ }
+ }
} on FileSystemException {
throw const RepositoryCloneException(
'Could not create a project folder. Choose Local to select a folder you can edit.',
);
+ } on ProcessException {
+ throw const RepositoryCloneException(
+ 'Could not create a project folder. Choose Local to select a folder you can edit.',
+ );
}
}
}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index da8953bea..f8e78567c 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -2764,8 +2764,7 @@ class AppNotifier extends ChangeNotifier {
) {
if (state.localOnly && localEndpoint?.computerId == localComputerId) {
state.localEndpoint = localEndpoint;
- state.transportMode =
- state.connectionStatus == ConnectionStatus.connected
+ state.transportMode = state.connectionStatus == ConnectionStatus.connected
? MachineTransportMode.localPlaintext
: MachineTransportMode.localOffline;
} else if (state.localOnly) {
@@ -2793,14 +2792,14 @@ class AppNotifier extends ChangeNotifier {
// threw first and threw away an answer that was already correct, while awaiting it FIRST would let a
// slow probe hold up the list. Latch it as it lands instead, and use it on both paths.
LocalCliEndpoint? probed;
- final localSettled = localFuture.then((value) => probed = value).catchError((
- Object error,
- ) {
- // A probe that fails is the CLI being unreachable, which the transport decision below already
- // handles — but swallowing it silently leaves nothing to diagnose from.
- debugPrint('local CLI probe failed: $error');
- return null;
- });
+ final localSettled = localFuture.then((value) => probed = value).catchError(
+ (Object error) {
+ // A probe that fails is the CLI being unreachable, which the transport decision below already
+ // handles — but swallowing it silently leaves nothing to diagnose from.
+ debugPrint('local CLI probe failed: $error');
+ return null;
+ },
+ );
final List<Machine> list;
try {
list = await _fetchMachines();
@@ -4789,10 +4788,7 @@ class AppNotifier extends ChangeNotifier {
target.arrangedKey = key;
}
if (firstAgent && target.name == Swarm.defaultName) {
- final name = agent.name.trim();
- if (name.isNotEmpty) {
- target.name = name.length > 80 ? name.substring(0, 80) : name;
- }
+ target.name = _nextHarnessName();
}
if (replaced != null && !allPanes.contains(replaced)) {
// Release just the desktop stream. The CLI agent process keeps running.
@@ -5276,6 +5272,25 @@ class AppNotifier extends ChangeNotifier {
Future<void> flushPaneLayout() =>
_paneLayout?.flushSwarms() ?? Future<void>.value();
+ String _nextHarnessName() {
+ var next = BigInt.one;
+ final names = [
+ for (final swarm in swarms) swarm.name,
+ for (final entry in _closedHistory)
+ if (entry is ClosedSwarm)
+ entry.name
+ else if (entry is ClosedAgent)
+ entry.swarmName,
+ ];
+ for (final name in names) {
+ final match = RegExp(r'^harness-([1-9]\d*)$').firstMatch(name);
+ if (match == null) continue;
+ final number = BigInt.parse(match.group(1)!);
+ if (number >= next) next = number + BigInt.one;
+ }
+ return 'harness-$next';
+ }
+
void _persistLayout() {
_draftSwarmReturns.removeWhere((id, _) {
final swarm = swarms.where((swarm) => swarm.id == id).firstOrNull;
diff --git a/desktop/lib/widgets/new_agent_dialog.dart b/desktop/lib/widgets/new_agent_dialog.dart
index e13ed2522..d37b75059 100644
--- a/desktop/lib/widgets/new_agent_dialog.dart
+++ b/desktop/lib/widgets/new_agent_dialog.dart
@@ -693,7 +693,7 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
child: Align(
alignment: Alignment.centerLeft,
child: Text(
- 'Creates a new folder in ~/Harness Projects.',
+ 'Creates a new folder in ~/harnesses.',
style: Theme.of(context).textTheme.bodySmall
?.copyWith(color: grid.AppPalette.textSecondary),
),
@@ -729,7 +729,7 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {
),
const SizedBox(height: 6),
Text(
- 'Clone into ~/Harness Projects on $_machineName.',
+ 'Clone into ~/harnesses on $_machineName.',
style: Theme.of(context).textTheme.bodySmall
?.copyWith(color: grid.AppPalette.textSecondary),
),
diff --git a/desktop/test/project_folder_test.dart b/desktop/test/project_folder_test.dart
index 1c60fa3a1..04e863dfc 100644
--- a/desktop/test/project_folder_test.dart
+++ b/desktop/test/project_folder_test.dart
@@ -21,9 +21,16 @@ void main() {
request.prepareLocal(projectHome: root.path),
]);
expect(folders.toSet(), hasLength(2));
+ expect(folders.map(p.basename).toSet(), {'agent-1', 'agent-2'});
expect(folders.every((folder) => p.isWithin(root.path, folder)), isTrue);
expect(await existing.readAsString(), 'keep');
expect(request.payload, {'projectSource': 'new'});
+ await File(p.join(root.path, 'agent-4')).writeAsString('keep');
+ expect(
+ p.basename(await request.prepareLocal(projectHome: root.path)),
+ 'agent-5',
+ );
+ expect(await File(p.join(root.path, 'agent-4')).readAsString(), 'keep');
},
);
test(
diff --git a/desktop/test/swarm_state_test.dart b/desktop/test/swarm_state_test.dart
index 669983d56..01c13779f 100644
--- a/desktop/test/swarm_state_test.dart
+++ b/desktop/test/swarm_state_test.dart
@@ -138,7 +138,7 @@ void main() {
'New Harness',
]) {
test(
- '$legacy empty tabs restore as New Harness and still name the first agent',
+ '$legacy empty tabs restore as New Harness and number the first occupied tab',
() async {
final store = MemoryStore();
final original = createApp(store: store);
@@ -155,7 +155,7 @@ void main() {
await restored.restorePaneLayoutForTest();
expect(restored.activeSwarm.name, 'New Harness');
await restored.addAgentToSwarm('m', 'a0');
- expect(restored.activeSwarm.name, 'Agent 0');
+ expect(restored.activeSwarm.name, 'harness-1');
},
);
}
@@ -166,13 +166,13 @@ void main() {
final app = createApp();
addTearDown(app.dispose);
await app.addAgentToSwarm('m', 'a0');
- expect(app.activeSwarm.name, 'Agent 0');
+ expect(app.activeSwarm.name, 'harness-1');
await app.addAgentToSwarm('m', 'a1');
- expect(app.activeSwarm.name, 'Agent 0');
- expect(app.activeSwarm.toJson()['name'], 'Agent 0');
+ expect(app.activeSwarm.name, 'harness-1');
+ expect(app.activeSwarm.toJson()['name'], 'harness-1');
await app.closeSwarm(app.activeSwarmId);
app.reopenClosedSwarm();
- expect(app.activeSwarm.name, 'Agent 0');
+ expect(app.activeSwarm.name, 'harness-1');
},
);
@@ -188,11 +188,33 @@ void main() {
final target = app.activeSwarm;
app.newSwarm(name: 'Elsewhere');
await app.addAgentToSwarm('m', 'a1', swarmId: target.id);
- expect(target.name, 'Agent 1');
+ expect(target.name, 'harness-1');
expect(app.activeSwarm.name, 'Elsewhere');
},
);
+ test('tab numbering skips saved and recently closed names', () async {
+ final store = MemoryStore();
+ final app = createApp(store: store);
+ await app.addAgentToSwarm('m', 'a0');
+ app.newSwarm();
+ await app.addAgentToSwarm('m', 'a1');
+ expect(app.activeSwarm.name, 'harness-2');
+ await app.closeSwarm(app.activeSwarmId);
+ app.newSwarm();
+ await app.addAgentToSwarm('m', 'a2');
+ expect(app.activeSwarm.name, 'harness-3');
+ app.renameSwarm(app.activeSwarmId, 'harness-10');
+ await app.flushPaneLayout();
+ app.dispose();
+ final restored = createApp(store: store);
+ addTearDown(restored.dispose);
+ await restored.restorePaneLayoutForTest();
+ restored.newSwarm();
+ await restored.addAgentToSwarm('m', 'a3');
+ expect(restored.activeSwarm.name, 'harness-11');
+ });
+
test(
'shared memberships own one controller and close only the final stream',
() async {
diff --git a/docs/harness-v2-handoff.md b/docs/harness-v2-handoff.md
index 5cc4c797e..d816317ca 100644
--- a/docs/harness-v2-handoff.md
+++ b/docs/harness-v2-handoff.md
@@ -34,22 +34,31 @@ user for a benchmark window.
## Current product contract
-### Pending: friendly defaults and a fresh New Agent design
-
-The user requests `~/Harnesses` instead of `~/Harness Projects`, default agent
-names `agent-1`, `agent-2`, …, and automatic tab names `harness-1`, `harness-2`, ….
-These naming changes are not implemented yet. Preserve existing folders and
-custom names. Folder creation lives in `desktop/lib/core/project_folder.dart`
-and `cli/src/lib/projectFolder.ts`; agent naming is in the CLI registry; tab
-auto-naming is in `AppNotifier.assignAgentToPane`.
-
-The user now wants to discuss a fresh New Agent design before implementation:
-as spacious as Open Agent, focused on the fastest path to starting an agent.
-Do not merely enlarge the existing form. The quiet picker cleanup below is
-verified locally, but publishing was rejected by automatic approval review and
-a renewed GitHub approval question is pending. The latest installed preview is
-**0c764cf** (receipt `/private/tmp/harness-minimal-preview-install.json`);
-subsequent search/device/chooser refinements have not been installed yet.
+### Friendly defaults
+
+New project folders use `~/harnesses/agent-1`, `agent-2`, …, with exclusive
+creation so simultaneous requests never share a folder. New Harness-created
+agents receive stable `agent-1`, `agent-2`, … names; user names and existing
+discovered agents remain unchanged. The first agent in an unnamed tab gives it
+`harness-1`, `harness-2`, …, skipping current and recently closed names.
+Fifty Flutter checks, 69 CLI checks, static analysis and CLI typechecking pass.
+Logs: `/private/tmp/harness-friendly-names-tests.log` and
+`/private/tmp/harness-friendly-names-cli-tests.log`.
+
+### Approved next: project picker in New Agent
+
+Build Agent → Machine → Project in a dialog as spacious as Open Agent. Keep
+Codex, Claude Code and OpenCode visible in stable order; show all machines.
+Project combines a pinned New project, recent folders, search, Git URL and
+Browse. Arrow selection updates a preview from README, Git history, contributors
+and files. Enter selects and collapses into a project bar; clicking it searches
+again. Remember the last project per machine; first use selects New project.
+Profiles and permissions stay in Options. Cmd-Return creates the agent.
+The user has renewed authorization to push each completed feature separately.
+
+The latest installed preview is **0c764cf** (receipt
+`/private/tmp/harness-minimal-preview-install.json`); later search/device/chooser
+refinements have not been installed yet.
### Quiet agent choices