agentic-dev-env

Reproducible development environment for agentic coding with OpenCode and OpenSpec.

New machine quickstart

# 1. Clone this repo
git clone git@github.com:GusRCSilva/agentic-dev-env.git ~/Repos/agentic-dev-env
cd ~/Repos/agentic-dev-env

# 2. Run the installer (requires sudo for system packages)
bash install.sh

# 3. Configure git identity
git config --global user.name   "Your Name"
git config --global user.email  "your@email.com"

# 4. Generate SSH key and add to GitHub
ssh-keygen -t ed25519 -C "your@email.com"
cat ~/.ssh/id_ed25519.pub   # → paste into https://github.com/settings/keys

# 5. Authenticate CLIs
gh auth login
glab auth login

# 6. Clone your projects and go
git clone git@github.com:GusRCSilva/hello-openspec.git ~/Repos/hello-openspec
cd ~/Repos/hello-openspec
opencode

Prerequisites

• macOS or Linux (Debian/Ubuntu, Fedora, or Homebrew-installed)
• git, curl (auto-installed by the script)
• tmux (optional, for opencode-workspace)

What it installs

Tool	Purpose
opencode	Terminal-native AI coding agent
openspec	Spec-driven development framework
opencode-workspace	Tmux-based opencode launcher
gh	GitHub CLI
glab	GitLab CLI
semgrep	Static analysis
uv	Python package manager
Node.js >= 22	Runtime

MCP servers configured

config/opencode.json is copied to ~/.config/opencode/opencode.json with:

• notion — Notion API
• gitlab — GitLab CLI
• playwright — Browser automation
• fetch — HTTP requests
• semgrep — Code scanning
• aws-knowledge — AWS documentation
• sequential-thinking — Structured reasoning
• brave-search — Web search
• github — GitHub API

Secrets

API tokens are stored in ~/.local/share/opencode/mcp.env (XDG data dir). They are never committed to any repo.

Token	Required for
GITHUB_TOKEN	GitHub MCP server
NOTION_TOKEN	Notion MCP server
BRAVE_API_KEY	Brave Search MCP server

How secrets reach opencode

~/.local/share/opencode/mcp.env     ← KEY=VALUE secrets (never committed)
         │
         ├─[opencode-workspace]────  reads file, injects into process.env
         │
         └─[shell profile]────────  eval "$(sed 's/^/export /' mcp.env)"
                                         │
                                    opencode resolves {env:GITHUB_TOKEN}

Two paths, same result:

1. opencode-workspace (recommended) — loads mcp.env automatically from JS
2. Shell profile — install.sh appends a sourcing block to ~/.bashrc / ~/.zshrc

Run source ~/.bashrc (or open a new shell) after installation to pick up secrets.

Adding a new secret

# via opencode-workspace
opencode-workspace mcp env MY_API_KEY

# or manually
echo "MY_API_KEY=sk-..." >> ~/.local/share/opencode/mcp.env

Then reference it in config/opencode.json with {env:MY_API_KEY}.

Spec-driven workflow

After setup, initialize OpenSpec in any project:

cd your-project
openspec init --tools opencode

Then use these slash commands in opencode:

Command	What it does
/opsx:propose "idea"	Creates proposal.md, spec deltas, design.md, tasks.md
/opsx:apply	Implements tasks one by one
/opsx:archive	Merges spec deltas into source-of-truth, archives the change
/opsx:explore	Browse existing specs

Customizing

• Edit config/opencode.json to add/remove MCP servers
• Edit install.sh to add tools specific to your stack
• The repo is yours — fork it and make it your own