llm-workspace

A portable AI coding-agent workspace for OpenAI Codex, Claude Code, Cursor, and other developer agents.

llm-workspace is an open-source, cross-harness repository for managing AI agent skills, coding-agent instructions, context engineering, agent memory, project knowledge, decisions, task records, and generated reports. It keeps AI development files outside the application repository while making the same reusable knowledge available across Codex, Claude Code, and Cursor.

Designed for

• AI coding agents and agentic software development
• Portable Agent Skills and reusable SKILL.md workflows
• Claude Code skills and CLAUDE.md project instructions
• OpenAI Codex skills and AGENTS.md instructions
• Cursor rules, Cursor skills, and multi-root workspaces
• Context engineering, prompt management, and LLM developer tooling
• Persistent agent memory and searchable AI knowledge bases
• Multi-agent and multi-harness development teams
• AI task reports, architecture decisions, and engineering handoffs

Recommended layout

MyProject/
├── code/                 # The application repository
└── llm/                  # Clone of this repository

The two directories are separate Git repositories. AI history stays in llm; source code and product documentation stay in code.

Start a project

mkdir MyProject
cd MyProject
git clone https://github.com/YOUR_USER/YOUR_CODE_REPO.git code
git clone https://github.com/YOUR_USER/llm-workspace.git llm
cd llm
python3 scripts/sync_skills.py codex   # or: claude / cursor

Install globally on your computer

Global installation makes the skills available in every project for the current user. Run the installer once after cloning this repository.

Linux and macOS:

./scripts/install.sh

Windows PowerShell:

.\scripts\install.ps1

Windows Command Prompt:

scripts\install.cmd

With no arguments, each launcher installs all skills globally for Cursor, Claude Code, and Codex. It uses these user directories:

~/.cursor/skills/     Cursor
~/.claude/skills/     Claude Code
~/.agents/skills/     Codex

The installer copies only the canonical folders under skills/, marks its own copies, preserves unrelated user skills, and refuses to overwrite unmanaged folders with the same name.

Manage the installation with the same launcher and an explicit action:

./scripts/install.sh update --scope global --harness all
./scripts/install.sh doctor --scope global --harness all
./scripts/install.sh uninstall --scope global --harness all

PowerShell and CMD accept the same arguments. Restart a harness if it does not detect a newly created top-level skills directory during the current session.

Then open or launch both folders:

• Codex: from llm, run codex --add-dir ../code
• Claude Code: from llm, run claude --add-dir ../code
• Cursor: open llm-workspace.code-workspace

If the code directory is not named code, edit the workspace file or pass the correct path to the command.

What belongs here

skills/                   canonical reusable agent skills
library/inbox/            new AI work waiting to be curated
library/tasks/            completed task records and verification
library/knowledge/        durable architecture, patterns, and conventions
library/decisions/        important decisions and their reasoning
library/archive/          superseded material retained for history
reports/                  generated reviews, audits, and investigations
scripts/                  synchronization and validation utilities

Do not store secrets, credentials, customer data, raw private transcripts, or large build artifacts here. Link task records to a code branch, commit, issue, or pull request instead of copying source code into the library.

Daily workflow

1. Start the AI tool from this repository with the code repository attached.
2. Search library/ before beginning work.
3. Make code changes only in the code repository.
4. Record the outcome with library/templates/task-record.md.
5. Move reusable findings into library/knowledge/ or library/decisions/.
6. Commit the code and AI workspace independently, cross-linking their commits.

Add a skill

Create skills/<skill-name>/SKILL.md, then run:

python3 scripts/validate.py
python3 scripts/sync_skills.py codex

skills/ is the source of truth. The sync command installs copies into the directory expected by the selected harness. Generated harness directories are ignored by Git to avoid duplicate sources and noisy commits.

Share one AI workspace across projects

The simplest model is one clone per project, each with project-specific library content. Reusable skills can be merged back into this public template. For a single centrally managed clone, place it beside multiple code repos and create a separate .code-workspace file for each project.

License

MIT