1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
#!/usr/bin/env bash
# install-ai.sh — bootstrap .ai/ in a fresh project from canonical source.
#
# Refuses if PROJECT/.ai/ already exists. Use `make audit APPLY=1` to
# update an existing .ai/ instead.
#
# Usage: install-ai.sh [--track | --gitignore] [PROJECT_PATH]
#
# If PROJECT_PATH is omitted, fzf-pick from ~/code/* + ~/projects/* git
# checkouts that don't already have a .ai/ directory.
set -euo pipefail
REPO="$(cd "$(dirname "$0")/.." && pwd)"
CANONICAL="$REPO/claude-templates/.ai"
project=""
track_mode=""
for arg in "$@"; do
case "$arg" in
--track) track_mode="track" ;;
--gitignore) track_mode="gitignore" ;;
-h|--help)
cat <<EOF
Usage: $(basename "$0") [--track | --gitignore] [PROJECT_PATH]
Bootstrap .ai/ in PROJECT_PATH from canonical content at $CANONICAL.
--track Track .ai/ in the project's git history (with .gitkeep
files inside otherwise-empty sessions/, references/,
retrospectives/).
--gitignore Gitignore the project's personal tooling (.ai/, .claude/,
CLAUDE.md, AGENTS.md) so it stays local. .claude/ is
rulesets-owned and re-synced each startup, so git isn't how
it travels; ignoring it also keeps private rule copies out
of the repo.
If neither flag is given, the script prompts interactively.
If PROJECT_PATH is omitted, fzf-picks from ~/code/* + ~/projects/*
git checkouts without an existing .ai/.
EOF
exit 0
;;
-*)
echo "ERROR: unknown flag: $arg (use --help for usage)" >&2
exit 2
;;
*)
if [ -n "$project" ]; then
echo "ERROR: multiple PROJECT_PATH arguments: $project and $arg" >&2
exit 2
fi
project="$arg"
;;
esac
done
# Project resolution: argument or fzf-pick.
if [ -z "$project" ]; then
if ! command -v fzf >/dev/null 2>&1; then
echo "ERROR: PROJECT_PATH not given and fzf is not installed" >&2
exit 2
fi
project=$(
find "$HOME/code" "$HOME/projects" -maxdepth 2 -mindepth 1 -type d -name .git 2>/dev/null \
| sed 's|/\.git$||' \
| while read -r p; do
if [ ! -e "$p/.ai" ]; then echo "$p"; fi
done \
| sort \
| fzf --prompt="Target project (without .ai/)> "
)
if [ -z "$project" ]; then
echo "No target selected." >&2
exit 1
fi
fi
# Validate project path.
if [ ! -d "$project" ]; then
echo "ERROR: $project is not a directory" >&2
exit 2
fi
project="$(cd "$project" && pwd)"
# Refuse if .ai/ already exists.
if [ -e "$project/.ai" ]; then
echo "ERROR: $project/.ai already exists" >&2
echo " Use 'make audit APPLY=1' to sync an existing .ai/ instead." >&2
exit 2
fi
# Warn if not a git checkout.
if [ ! -d "$project/.git" ]; then
echo "WARN: $project is not a git checkout — track/gitignore handling will be skipped"
fi
# Decide track vs gitignore (skip if no .git).
if [ -d "$project/.git" ] && [ -z "$track_mode" ]; then
echo
echo "Track .ai/ in git, or add to .gitignore?"
echo " [t] track — .ai/ enters git history, session records persist for the team"
echo " [g] gitignore — .ai/ stays local, session records private to this machine"
printf "Choice [t/g]: "
read -r answer
case "$answer" in
t|T|track) track_mode="track" ;;
g|G|gitignore) track_mode="gitignore" ;;
*)
echo "ERROR: invalid choice (rerun with --track or --gitignore)" >&2
exit 2
;;
esac
fi
echo
echo "Installing .ai/ at $project/.ai/ ..."
# Create directory structure.
mkdir -p "$project/.ai/sessions"
mkdir -p "$project/.ai/references"
mkdir -p "$project/.ai/retrospectives"
# Top-level inbox/ — the cross-project messaging target (inbox-send needs a
# .ai/ marker AND a top-level inbox/). Created in both track and gitignore
# modes since inbox/ is a project-root convention independent of .ai/
# tracking. Idempotent: a pre-existing inbox/ and its contents are preserved.
mkdir -p "$project/inbox"
touch "$project/inbox/.gitkeep"
# Rsync canonical content (everything except notes.org, which gets templated).
rsync -a "$CANONICAL/protocols.org" "$project/.ai/protocols.org"
rsync -a "$CANONICAL/someday-maybe.org" "$project/.ai/someday-maybe.org"
rsync -a --delete "$CANONICAL/workflows/" "$project/.ai/workflows/"
rsync -a --delete "$CANONICAL/scripts/" "$project/.ai/scripts/"
# Seed notes.org with placeholder substitution.
project_name="$(basename "$project")"
today="$(date +%Y-%m-%d)"
sed "s|\[Project Name\]|$project_name|g; s|\[Date\]|$today|g" \
"$CANONICAL/notes.org" > "$project/.ai/notes.org"
# Tracking setup.
case "$track_mode" in
track)
# .gitkeep files so otherwise-empty dirs survive in git.
touch "$project/.ai/sessions/.gitkeep"
touch "$project/.ai/references/.gitkeep"
touch "$project/.ai/retrospectives/.gitkeep"
;;
gitignore)
# Personal-tooling files that stay out of git in gitignore mode. .ai/
# holds session records; .claude/ is rulesets-owned bundle content
# (re-synced each startup, and it carries private rule copies); CLAUDE.md
# and AGENTS.md are personal tooling, project-owned but never committed.
# Append only the lines not already present, so a project that already
# ignores some of them isn't duplicated.
gi="$project/.gitignore"
needed=()
for pat in '.ai/' '.claude/' 'CLAUDE.md' 'AGENTS.md'; do
if [ -f "$gi" ] && grep -qFx "$pat" "$gi"; then continue; fi
needed+=("$pat")
done
if [ "${#needed[@]}" -gt 0 ]; then
{
[ -s "$gi" ] && echo ""
echo "# Claude Code per-project tooling"
printf '%s\n' "${needed[@]}"
} >> "$gi"
fi
;;
esac
# Banner.
echo
echo "Done."
echo
echo " project: $project"
echo " tracking: ${track_mode:-not-a-git-repo}"
echo " notes.org: project=$project_name, date=$today"
echo " inbox/: created (inbox-send target)"
echo
echo "Next steps:"
echo " - Add a language bundle: make install-lang PROJECT=$project"
echo " - Start a Claude session: cd $project && claude"
|
