agent-home

Sync global agent instructions and personal skills across computers and harnesses through Git. Particularly useful when running agents on remote development machines.

Set up your repository

You need Python 3.10+, Git, and GitHub authentication on each computer.

Your personal context stays in your private repository, while program updates come from this public project.

Do this once. If you already have your private repository, continue with Installation.

Create an empty private repository on GitHub, for example agent-home-personal, then run:

git clone https://github.com/adrilasar/agent-home.git agent-home-personal
cd agent-home-personal
git remote rename origin upstream
git remote add origin https://github.com/YOUR-ACCOUNT/YOUR-REPO.git
git config remote.pushDefault origin
git push -u origin main

Replace YOUR-ACCOUNT/YOUR-REPO with your private repository's path. The repository and local folder names are your choice.

origin points to your repository; upstream points to this public project for future updates.

Installation

If you just completed setup, continue in the same directory.

On another computer, clone your private repository first:

git clone https://github.com/YOUR-ACCOUNT/YOUR-REPO.git agent-home-personal
cd agent-home-personal
git remote add upstream https://github.com/adrilasar/agent-home.git

Choose a computer name using lowercase letters, numbers and hyphens.

If you already have global instructions or personal skills, copy them into the repository before installing. Use common/FRAGMENT.md for shared instructions, machines/COMPUTER-NAME/FRAGMENT.md for computer-specific instructions, and skills/ folders in either scope for skills. Create the files and folders as needed, then commit and push your changes. Installation replaces managed files; it does not merge their existing content.

From your personal clone, run:

# Windows: py -3 agent_home.py install COMPUTER-NAME codex claude
python3 agent_home.py install COMPUTER-NAME codex claude

Replace COMPUTER-NAME with the name you chose. Available harnesses are codex and claude; list the ones you want to configure. This selects which global instruction files to generate from your fragments (AGENTS.md for Codex, CLAUDE.md for Claude Code) and where to copy your skills.

You can run install again to change the configured harnesses. The command shows the changes and asks for confirmation when reinstalling.

Installation applies the files and schedules synchronization every 15 minutes.

Usage and synchronization

Ask your agent to update your global instructions or personal skills, or edit the repository sources yourself. The included manage-personal-context skill provides agents with the repository and synchronization details.

Installed copies are generated. Once changes reach your repository's main, your computers receive them automatically. To sync immediately, run from the installation clone recorded in ~/.agent-home/state.json (repo):

# Windows: py -3 agent_home.py sync
python3 agent_home.py sync

Automatic synchronization requires the installation clone to be on main, with no uncommitted changes or unpublished commits. For branch/PR work, use another clone or worktree. Run sync only from the installation clone once changes reach origin/main; the installation state belongs to that clone.

Receive project updates

To bring updates from the public project into your private repository:

git switch main
git pull --ff-only origin main
git fetch upstream
git merge upstream/main
git push origin main

You choose when to bring in public updates.

Organization

Sources are combined in this order:

1. common/: all computers and harnesses.
2. harnesses/<harness>/: one harness (codex or claude).
3. machines/<computer>/: one computer.
4. machines/<computer>/harnesses/<harness>/: one combination.

Each scope can contain:

• FRAGMENT.md: instructions concatenated into the global instructions file.
• skills/<name>/SKILL.md and resources: skills copied in full. Skill names must be unique across the selected scopes.

Example: combining instruction fragments

common/FRAGMENT.md:

Keep explanations concise.

machines/example/FRAGMENT.md:

This computer is named `example`.

On the example computer, the generated AGENTS.md or CLAUDE.md combines both:

<!-- Generated by agent-home. Edit the repository sources. -->

<!-- common/FRAGMENT.md -->
Keep explanations concise.

<!-- machines/example/FRAGMENT.md -->
This computer is named `example`.

Files are installed into:

• Codex: ~/.codex/AGENTS.md and ~/.codex/skills/ (respects CODEX_HOME at installation).
• Claude Code: ~/.claude/CLAUDE.md and ~/.claude/skills/.

Sync keeps using the Codex directory chosen at installation, even if CODEX_HOME changes or is unset. To change that directory, run install again with the desired CODEX_HOME (or unset it to use ~/.codex). Existing installations keep the directory recorded in their managed file paths.

This program manages global instructions and personal skills. It does not modify instructions or skills inside project repositories.

Uninstallation

# Windows: py -3 agent_home.py uninstall
python3 agent_home.py uninstall

Removes scheduled synchronization, state, and backups. Preserves installed instructions, skills, and the repository clone.

License

MIT. See LICENSE.