{"id":481779,"date":"2026-05-31T13:36:30","date_gmt":"2026-05-31T13:36:30","guid":{"rendered":"https:\/\/savepearlharbor.com\/?p=481779"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T21:00:00","slug":"","status":"publish","type":"post","link":"https:\/\/savepearlharbor.com\/?p=481779","title":{"rendered":"AI Workspace System: one local workspace for Codex, Claude Code, and GitHub"},"content":{"rendered":"
\n

I ran into a very practical problem after doing a lot of local work with AI agents. I had Codex projects, Claude Code projects, regular repositories edited with agents, drafts, pipelines, instructions, skills, artifacts, and several machines. At some point it became hard to tell where the current version of a project lived, which files were safe to push, where agent instructions belonged, and where source code had already been mixed with logs and intermediate output.<\/p>\n

That is why I built AI Workspace System<\/code>: a small set of shell scripts, conventions, and Markdown documentation that makes local AI-agent work predictable. It is not an IDE and not an agent orchestrator. It is a thin infrastructure layer around Git, GitHub, Codex, and Claude Code.<\/p>\n

The core idea is simple: all projects should be visible from one list, instructions should follow one structure, sync should be safe by default, and machine-specific details should not live in the repository.<\/p>\n

<\/figure>\n

What the project does<\/h3>\n

First, it provides one launcher for Codex and Claude Code. ai-launch codex<\/code> or ai-launch claude<\/code> shows a project list. The first items are always New project<\/code> and No project<\/code>: create a project or start an agent without project context.<\/p>\n

Second, it defines one instruction model. AGENTS.md<\/code><\/a> is the canonical shared instruction file. CLAUDE.md<\/code><\/a> imports it with @<\/code>AGENTS.md<\/code><\/a> and contains only Claude Code-specific notes.<\/p>\n

Third, it includes a conservative workspace-sync<\/code>. It fetches remotes, pulls only clean worktrees, pushes already committed changes, and skips dirty repositories. In scheduled mode it never commits automatically.<\/p>\n

Fourth, it separates owned repositories from upstream repositories. If origin<\/code> is external, scheduled sync pushes only to a separate backup<\/code> remote. Pushing to the real upstream must be an explicit action.<\/p>\n

Fifth, it separates target repos from delivery workbenches. A target repo contains reviewed code and public material. A workbench contains prompts, research, drafts, pipelines, and local state. The relationship is described in workspace.yaml<\/code>.<\/p>\n

How to use it<\/h3>\n

Minimal setup:<\/p>\n

mkdir -p ~\/projectsgit clone <ai-workspace-system-repo-url> ~\/projects\/ai-workspace-system~\/projects\/ai-workspace-system\/bin\/install-localworkspace-configure<\/code>
<\/a><\/div><\/pre>\n
install-local<\/code> creates symlinks in ~\/.local\/bin<\/code>, and workspace-configure<\/code> writes local configuration:<\/p>\n
~\/.config\/ai-workspace\/config<\/code>
<\/a><\/div><\/pre>\n
The config contains everything that belongs to the current machine:<\/p>\n
PROJECTS_HOME=\"$HOME\/projects\"PROJECT_ROOTS=\"$HOME\/projects\"SYNC_ROOTS=\"$HOME\/projects\"GITHUB_ORG=\"\"BACKUP_REMOTE=\"backup\"CODEX_BIN=\"$HOME\/.local\/bin\/codex\"CLAUDE_BIN=\"$HOME\/.local\/bin\/claude\"SECRET_SCAN_CMD=\"\"<\/code>
<\/a><\/div><\/pre>\n
PROJECT_ROOTS<\/code> controls the picker. SYNC_ROOTS<\/code> controls scheduled sync. A project can be visible to agents without being part of automatic sync.<\/p>\n
After setup:<\/p>\n
ai-launch codexai-launch claude<\/code>
<\/a><\/div><\/pre>\n
The agent does not start in a random directory. The launcher first shows New project<\/code>, No project<\/code>, then projects from PROJECT_ROOTS<\/code>. New project<\/code> calls workspace-new-project<\/code>: it creates a directory under PROJECTS_HOME<\/code>, writes baseline README.md<\/code><\/a>, AGENTS.md<\/code><\/a>, CLAUDE.md<\/code><\/a>, workspace.yaml<\/code>, .gitignore<\/code>, and .env.example<\/code>, then runs git init -b main<\/code> and creates an initial commit. No project<\/code> is for one-off questions.<\/p>\n
Scheduled sync uses a user-level systemd timer at 13:00, 19:00, and 23:50:<\/p>\n
systemctl --user daemon-reloadsystemctl --user enable --now ai-workspace-sync.timer<\/code>
<\/a><\/div><\/pre>\n
Before enabling it:<\/p>\n
workspace-sync --dry-run<\/code>
<\/a><\/div><\/pre>\n
This shows which repositories will be discovered.<\/p>\n
Prompt for collecting local projects<\/h3>\n
Another key part is prompts\/<\/code>discover-and-normalize-local-projects.md<\/code><\/a>. Give it to Codex or Claude Code on a machine where projects are scattered across the home directory. It asks the agent to inventory directories, classify candidates, propose a move plan, move safe projects, add README.md<\/code><\/a>, AGENTS.md<\/code><\/a>, CLAUDE.md<\/code><\/a>, .gitignore<\/code>, and workspace.yaml<\/code>, and initialize Git only where the directory is a real project rather than an archive, cache, or runtime state.<\/p>\n
Short version:<\/p>\n
Find likely local projects, classify them, move approved ones into ~\/projects,add baseline AI\/project docs, and initialize Git repos where appropriate.Do not move secrets, agent sessions, logs, caches, auth files, or shell history.Preserve existing remotes. Ask before committing dirty repos or changing upstream policy.<\/code>
<\/a><\/div><\/pre>\n
Global agent instructions<\/h3>\n
Global agent files are never overwritten blindly. ~\/.codex\/<\/code>AGENTS.md<\/code><\/a>, ~\/.claude\/<\/code>CLAUDE.md<\/code><\/a>, and ~\/.claude\/rules\/<\/code> are treated as machine-level preferences. If a file is missing, the agent may propose creating it. If it already exists, the agent should preserve its content and propose a small additive change. Runtime state, auth, sessions, logs, sqlite files, and shell history must not be committed.<\/p>\n
Commands<\/h3>\n
workspace-configure<\/code> writes local config: GitHub org or user, agent binary paths, project roots, and secret scanner.<\/p>\n
ai-launch codex<\/code> starts Codex through the project picker.<\/p>\n
ai-launch claude<\/code> starts Claude Code through the project picker.<\/p>\n
workspace-new-project <name><\/code> creates a project in PROJECTS_HOME<\/code>, initializes Git, and creates an initial commit. If GITHUB_ORG<\/code> is set, it can create a private GitHub repo.<\/p>\n
workspace-sync<\/code> performs safe sync: fetch, fast-forward pull for clean repositories, and push for committed changes.<\/p>\n
workspace-sync --scheduled<\/code> is used by the timer: no auto-commit, no force push, and no push to an external origin<\/code>.<\/p>\n
workspace-sync --commit<\/code> enables interactive mode: for dirty repos it asks whether to commit. If SECRET_SCAN_CMD<\/code> is set, it runs before the commit.<\/p>\n
workspace-ensure-backup --push<\/code> adds a backup remote for external upstream repositories.<\/p>\n
Limitations<\/h3>\n
GitHub sync is not a full backup. It does not replace restic<\/code>, borg<\/code>, or another real backup tool. Uncommitted documents, large artifacts, databases, dumps, and agent sessions should live elsewhere.<\/p>\n
Sync works only with Git repositories. If a project is not initialized as a Git repo, the launcher may show it, but sync will not preserve its state.<\/p>\n
Scheduled sync does not commit dirty worktrees. This is inconvenient sometimes, but intentional: automatic commits can publish secrets, temporary files, or half-finished work.<\/p>\n
The system does not guess policy for external repositories. If origin<\/code> does not belong to your GITHUB_ORG<\/code>, the project is treated as external. It can be backed up to backup<\/code>, but pushing to upstream requires an explicit command.<\/p>\n
It is also a shell-first system. It is transparent and easy to fix, but it does not provide a polished UI, operation history, or centralized project database.<\/p>\n
How we tuned it<\/h3>\n
The first version was personal: a specific GitHub organization, local roots, and a local secret-audit script. That is wrong for an open-source project: a user should provide their values during setup instead of removing somebody else\u2019s.<\/p>\n
The first fix was workspace-configure<\/code>. The repository now contains generic defaults, while real machine configuration lives in ~\/.config\/ai-workspace\/config<\/code>.<\/p>\n
The second fix was log placement. A sync log could end up inside the repository. Logs contain local paths, repo names, branches, and remotes. Now logs default to ~\/.local\/state\/ai-workspace\/logs<\/code>, and logs\/<\/code> is ignored.<\/p>\n
The third fix made workspace-new-project<\/code> independent of hardcoded ~\/projects<\/code>. It uses PROJECTS_HOME<\/code>, or the first item from PROJECT_ROOTS<\/code>. ai-launch<\/code> now uses the actual path printed by workspace-new-project<\/code>.<\/p>\n
The fourth fix was documentation cleanup. README, bootstrap prompts, templates, and playbooks use placeholders such as <ai-workspace-system-repo-url><\/code>, <github-org-or-user><\/code>, and <projects-home><\/code>.<\/p>\n
What broke and how it was fixed<\/h3>\n
One failure was conceptual: the system wanted to be both a working personal tool and a portable template. Hardcoded GitHub organization and local paths made it convenient on one machine but broke reuse. The fix was explicit setup through workspace-configure<\/code> and an empty GITHUB_ORG<\/code> in config.example<\/code>.<\/p>\n
Another failure was publication safety. A sync log got into the project working tree. It was not a secret by itself, but it exposed the structure of the home directory. The fix was to move logs to the XDG state directory and exclude logs\/<\/code> from Git.<\/p>\n
A third failure was secret scanning. workspace-sync --commit<\/code> called a private local script. That file does not exist on another machine. The fix was to make SECRET_SCAN_CMD<\/code> an optional local setting.<\/p>\n
The fourth failure was a Git hook. A global prepare-commit-msg<\/code> hook was supposed to add Signed-off-by<\/code>, but it used echo -e<\/code> under \/bin\/sh<\/code>. On this system, echo<\/code> printed -e<\/code> as text, so commit messages got an extra line. The portable fix:<\/p>\n
if [ -n \"$SOB\" ] && ! grep -qs \"^$SOB\" \"$1\"; then  printf '\\n%s\\n' \"$SOB\" >> \"$1\"fi<\/code>
<\/a><\/div><\/pre>\n
printf<\/code> is more predictable than echo -e<\/code> in shell scripts.<\/p>\n
The fifth failure was UX: project creation through the launcher assumed a fixed root. After introducing PROJECTS_HOME<\/code>, that was wrong. The fix was to make workspace-new-project<\/code> print the actual project path and make the launcher use it.<\/p>\n
The result is less \u201cmy local setup\u201d and more a small system. It still solves the same everyday task: open Codex or Claude Code, choose a project, safely sync state, and keep instructions from being lost. But personal decisions now live in local config, and the repository can be published and moved between machines.<\/p>\n
Repo: https:\/\/github.com\/tym83-ai\/ai-workspace-system<\/a><\/p>\n<\/div>\n
\u0441\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043e\u0440\u0438\u0433\u0438\u043d\u0430\u043b \u0441\u0442\u0430\u0442\u044c\u0438 https:\/\/habr.com\/ru\/articles\/1041798\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
I ran into a very practical problem after doing a lot of local work with AI agents. I had Codex projects, Claude Code projects, regular repositories edited with agents, drafts, pipelines, instructions, skills, artifacts, and several machines. At some point it became hard to tell where the current version of a project lived, which files were safe to push, where agent instructions belonged, and where source code had already been mixed with logs and intermediate output.That is why I built AI Workspace System: a small set of shell scripts, conventions, and Markdown documentation that makes local AI-agent work predictable. It is not an IDE and not an agent orchestrator. It is a thin infrastructure layer around Git, GitHub, Codex, and Claude Code.The core idea is simple: all projects should be visible from one list, instructions should follow one structure, sync should be safe by default, and machine-specific details should not live in the repository.What the project doesFirst, it provides one launcher for Codex and Claude Code. ai-launch codex or ai-launch claude shows a project list. The first items are always New project and No project: create a project or start an agent without project context.Second, it defines one instruction model. AGENTS.md is the canonical shared instruction file. CLAUDE.md imports it with @AGENTS.md and contains only Claude Code-specific notes.Third, it includes a conservative workspace-sync. It fetches remotes, pulls only clean worktrees, pushes already committed changes, and skips dirty repositories. In scheduled mode it never commits automatically.Fourth, it separates owned repositories from upstream repositories. If origin is external, scheduled sync pushes only to a separate backup remote. Pushing to the real upstream must be an explicit action.Fifth, it separates target repos from delivery workbenches. A target repo contains reviewed code and public material. A workbench contains prompts, research, drafts, pipelines, and local state. The relationship is described in workspace.yaml.How to use itMinimal setup:mkdir -p ~\/projectsgit clone <ai-workspace-system-repo-url> ~\/projects\/ai-workspace-system~\/projects\/ai-workspace-system\/bin\/install-localworkspace-configureinstall-local creates symlinks in ~\/.local\/bin, and workspace-configure writes local configuration:~\/.config\/ai-workspace\/configThe config contains everything that belongs to the current machine:PROJECTS_HOME=»$HOME\/projects»PROJECT_ROOTS=»$HOME\/projects»SYNC_ROOTS=»$HOME\/projects»GITHUB_ORG=»»BACKUP_REMOTE=»backup»CODEX_BIN=»$HOME\/.local\/bin\/codex»CLAUDE_BIN=»$HOME\/.local\/bin\/claude»SECRET_SCAN_CMD=»»PROJECT_ROOTS controls the picker. SYNC_ROOTS controls scheduled sync. A project can be visible to agents without being part of automatic sync.After setup:ai-launch codexai-launch claudeThe agent does not start in a random directory. The launcher first shows New project, No project, then projects from PROJECT_ROOTS. New project calls workspace-new-project: it creates a directory under PROJECTS_HOME, writes baseline README.md, AGENTS.md, CLAUDE.md, workspace.yaml, .gitignore, and .env.example, then runs git init -b main and creates an initial commit. No project is for one-off questions.Scheduled sync uses a user-level systemd timer at 13:00, 19:00, and 23:50:systemctl —user daemon-reloadsystemctl —user enable —now ai-workspace-sync.timerBefore enabling it:workspace-sync —dry-runThis shows which repositories will be discovered.Prompt for collecting local projectsAnother key part is prompts\/discover-and-normalize-local-projects.md. Give it to Codex or Claude Code on a machine where projects are scattered across the home directory. It asks the agent to inventory directories, classify candidates, propose a move plan, move safe projects, add README.md, AGENTS.md, CLAUDE.md, .gitignore, and workspace.yaml, and initialize Git only where the directory is a real project rather than an archive, cache, or runtime state.Short version:Find likely local projects, classify them, move approved ones into ~\/projects,add baseline AI\/project docs, and initialize Git repos where appropriate.Do not move secrets, agent sessions, logs, caches, auth files, or shell history.Preserve existing remotes. Ask before committing dirty repos or changing upstream policy.Global agent instructionsGlobal agent files are never overwritten blindly. ~\/.codex\/AGENTS.md, ~\/.claude\/CLAUDE.md, and ~\/.claude\/rules\/ are treated as machine-level preferences. If a file is missing, the agent may propose creating it. If it already exists, the agent should preserve its content and propose a small additive change. Runtime state, auth, sessions, logs, sqlite files, and shell history must not be committed.Commandsworkspace-configure writes local config: GitHub org or user, agent binary paths, project roots, and secret scanner.ai-launch codex starts Codex through the project picker.ai-launch claude starts Claude Code through the project picker.workspace-new-project <name> creates a project in PROJECTS_HOME, initializes Git, and creates an initial commit. If GITHUB_ORG is set, it can create a private GitHub repo.workspace-sync performs safe sync: fetch, fast-forward pull for clean repositories, and push for committed changes.workspace-sync —scheduled is used by the timer: no auto-commit, no force push, and no push to an external origin.workspace-sync —commit enables interactive mode: for dirty repos it asks whether to commit. If SECRET_SCAN_CMD is set, it runs before the commit.workspace-ensure-backup —push adds a backup remote for external upstream repositories.LimitationsGitHub sync is not a full backup. It does not replace restic, borg, or another real backup tool. Uncommitted documents, large artifacts, databases, dumps, and agent sessions should live elsewhere.Sync works only with Git repositories. If a project is not initialized as a Git repo, the launcher may show it, but sync will not preserve its state.Scheduled sync does not commit dirty worktrees. This is inconvenient sometimes, but intentional: automatic commits can publish secrets, temporary files, or half-finished work.The system does not guess policy for external repositories. If origin does not belong to your GITHUB_ORG, the project is treated as external. It can be backed up to backup, but pushing to upstream requires an explicit command.It is also a shell-first system. It is transparent and easy to fix, but it does not provide a polished UI, operation history, or centralized project database.How we tuned itThe first version was personal: a specific GitHub organization, local roots, and a local secret-audit script. That is wrong for an open-source project: a user should provide their values during setup instead of removing somebody else\u2019s.The first fix was workspace-configure. The repository now contains generic defaults, while real machine configuration lives in ~\/.config\/ai-workspace\/config.The second fix was log placement. A sync log could end up inside the repository. Logs contain local paths, repo names, branches, and remotes. Now logs default to ~\/.local\/state\/ai-workspace\/logs, and logs\/ is ignored.The third fix made workspace-new-project independent of hardcoded ~\/projects. It uses PROJECTS_HOME, or the first item from PROJECT_ROOTS. ai-launch now uses the actual path printed by workspace-new-project.The fourth fix was documentation cleanup. README, bootstrap prompts, templates, and playbooks use placeholders such as <ai-workspace-system-repo-url>, <github-org-or-user>, and <projects-home>.What broke and how it was fixedOne failure was conceptual: the system wanted to be both a working personal tool and a portable template. Hardcoded GitHub organization and local paths made it convenient on one machine but broke reuse. The fix was explicit setup through workspace-configure and an empty GITHUB_ORG in config.example.Another failure was publication safety. A sync log got into the project working tree. It was not a secret by itself, but it exposed the structure of the home directory. The fix was to move logs to the XDG state directory and exclude logs\/ from Git.A third failure was secret scanning. workspace-sync —commit called a private local script. That file does not exist on another machine. The fix was to make SECRET_SCAN_CMD an optional local setting.The fourth failure was a Git hook. A global prepare-commit-msg hook was supposed to add Signed-off-by, but it used echo -e under \/bin\/sh. On this system, echo printed -e as text, so commit messages got an extra line. The portable fix:if [ -n «$SOB» ] && ! grep -qs «^$SOB» «$1»; then  printf ‘\\n%s\\n’ «$SOB» >> «$1″fiprintf is more predictable than echo -e in shell scripts.The fifth failure was UX: project creation through the launcher assumed a fixed root. After introducing PROJECTS_HOME, that was wrong. The fix was to make workspace-new-project print the actual project path and make the launcher use it.The result is less \u201cmy local setup\u201d and more a small system. It still solves the same everyday task: open Codex or Claude Code, choose a project, safely sync state, and keep instructions from being lost. But personal decisions now live in local config, and the repository can be published and moved between machines.Repo: https:\/\/github.com\/tym83-ai\/ai-workspace-system\u0441\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043e\u0440\u0438\u0433\u0438\u043d\u0430\u043b \u0441\u0442\u0430\u0442\u044c\u0438 https:\/\/habr.com\/ru\/articles\/1041798\/<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-481779","post","type-post","status-publish","format-standard","hentry"],"_links":{"self":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/481779","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=481779"}],"version-history":[{"count":0,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/481779\/revisions"}],"wp:attachment":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=481779"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=481779"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=481779"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}