Cheatsheet شامل لكل أوامر وإعدادات وتراكيب OpenCode — الـ terminal AI coding agent.

OpenCode — Cheatsheet 📋

"الورقة اللي تطبعها وتعلقها جنب الـmonitor بتاعك"

SectionInstallation & Setup

Install

الطريقة	الأمر
Install script	`curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/main/install \| bash`
Homebrew (macOS/Linux)	`brew install opencode-ai/tap/opencode`
AUR (Arch)	`yay -S opencode-bin`
Nix	`nix run nixpkgs#opencode`
Go	`go install github.com/opencode-ai/opencode@latest`
Debian/Ubuntu	`dpkg -i opencode_*.deb`
Fedora/RHEL	`rpm -i opencode_*.rpm`
Windows	`scoop install opencode` أو `winget install OpenCode.OpenCode`

First Run

الأمر	بيعمل إيه	إمتى تستخدمه	ليه مهم
`opencode`	بيفتح الـTUI interactive	أول مرة تفتح المشروع	ده الـmain interface
`opencode -p "fix the bug"`	بينفذ prompt واحد ويخرج	CI/CD أو scripting	مش بياخذ input منك
`opencode -p "explain" -f json`	JSON output للـpiping	automation و pipelines	الـJSON structured
`opencode -p "explain" -q`	ساكن بدون spinner	CI/CD environments	clean output
`opencode --yolo`	كل tool calls تنفذ من غير permission	لما تثق في الـagent	⚠️ خطر لو مش عارف بتاعك

أوامر الـCLI الأساسية

➜ ~ opencode

يفتح الـinteractive TUI

➜ ~ opencode -p "fix the null pointer"

⠋ Running agent...

✓ Fixed auth/auth.go line 42

➜ ~ opencode -p "explain" -f json | jq .summary

"This function handles OAuth token refresh."

➜ ~⏎ نفّذ · ⌫ امسح

SectionCLI Commands

الأمر	بيعمل إيه بالظبط	إمتى تستخدمه	ليه مهم
`opencode`	بيفتح الـinteractive TUI — الـmain interface	الشغل اليومي	ده اللي بتستخدمه 90% من الوقت
`opencode -p "prompt"`	بينفذ prompt واحد في non-interactive mode ويخرج	CI/CD، scripts، automation	مش بيفتح TUI — بيطلع نتيجة ويخرج
`opencode -f json`	بيطلع الـoutput كـJSON structured	لما بتعمل pipeline أو parse	كل حاجة structured ومحددة
`opencode -q`	Quiet mode — بدون spinner أو decorations	CI/CD environments	clean output للـlogs
`opencode -c /path`	بيحدد working directory	لما بتشغل من مكان تاني	عشان الـagent يشتغل على المشروع الصح
`opencode serve`	بيبدأ shared workspace server	multi-client collaboration	تلتين TUI يقدروا يشتغلوا مع بعض
`opencode login`	بيعمل login للـsubscription providers	Gemini Code Assist, Copilot	provider محتاج auth
`opencode models`	بيعرض الـmodels المتاحة	لما تختار model	يعرفك إيه المتاح
`opencode stats`	بيعرض إحصائيات الاستخدام	مراقبة التكلفة	يعرفك كلفة كام
`opencode sessions`	بيعرض الـsessions المحفوظة	إدارة الـsessions	تعرف إيه اللي شغال
`opencode update-providers`	بيحدّث الـmodel database من Catwalk	لما في model جديد	يعرفك أحدث models
`opencode logs`	بيفتح الـinternal logs	debugging	يعرفك إيه حصل جوه

SectionAgent System — الأنواع والأدوار

Agent Taxonomy & Division of Labor

Agent Swarm Architecture

Primary Agents

الـAgent	الدور	Temperature	Permissions	إمتى تستخدمه
Build	الـdefault driver — بيعمل كل حاجة	0.3–0.5	Full file ops + system commands	الشغل اليومي — كتابة كود، تعديل، تنفيذ
Plan	الـanalyst — بيقرأ ويفهم بس	0.0–0.2	Ask-first لـ file edits + bash	لما عايز analysis أو architecture review
Title	بيولّد session titles	—	Read-only	اتوماتيكي — مش بنستخدمه يدوي

الـTab Key — تبدل بين Build و Plan في أي وقت.

Subagents

الـSubagent	الـAccess	الدور	إمتى تناديها
General	Full tools (except todo)	Multi-step task execution	لما الـtask محتاجة خطوات كتير
Explore	Read-only (glob, grep, ls, view)	Local codebase search	لما بتدور على حاجة في الكود
Scout	External researcher	External docs + dependency research	لما بتدور على docs أو upstream code

SectionConfiguration — `.opencode.json`

الـConfig الكامل

json

{
  "agents": {
    "coder": { "model": "claude-sonnet-4", "maxTokens": 5000 },
    "task": { "model": "claude-sonnet-4", "maxTokens": 5000 },
    "title": { "model": "claude-sonnet-4", "maxTokens": 80 }
  },
  "providers": {
    "anthropic": { "apiKey": "$ANTHROPIC_API_KEY" },
    "openai": { "apiKey": "$OPENAI_API_KEY" },
    "openrouter": { "apiKey": "$OPENROUTER_API_KEY" }
  },
  "permissions": {
    "allowed_tools": ["view", "ls", "grep", "glob", "edit"]
  },
  "mcp": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer $GH_PAT" }
    }
  },
  "lsp": {
    "go": { "command": "gopls" }
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "^(view|ls|grep|glob)$", "command": "echo '{\"decision\":\"allow\"}'" }
    ]
  },
  "options": {
    "context_paths": ["AGENTS.md", ".cursorrules"],
    "global_context_paths": ["~/.config/opencode/OPENCODE.md"],
    "tui": { "theme": "catppuccin", "compact_mode": false },
    "initialize_as": "AGENTS.md",
    "data_directory": ".opencode"
  }
}

Config Paths (بالترتيب)

الـPath	الأولوية
`./.opencode.json` (local)	أعلى — project-specific
`$XDG_CONFIG_HOME/opencode/.opencode.json`	user-level
`$HOME/.opencode.json`	user-level fallback

Provider Environment Variables

الـProvider	الـVariable	ملاحظات
Anthropic	`ANTHROPIC_API_KEY`	Claude models
OpenAI	`OPENAI_API_KEY`	GPT models
Google Gemini	`GEMINI_API_KEY`	Gemini models
AWS Bedrock	`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION`	Claude via AWS
Azure OpenAI	`AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_API_KEY`	GPT via Azure
OpenRouter	`OPENROUTER_API_KEY`	Multi-model access
GitHub Copilot	`GITHUB_TOKEN`	Free tier available
Groq	`GROQ_API_KEY`	Fast inference
Ollama	Local endpoint	Self-hosted
LM Studio	Local endpoint	Self-hosted
LiteLLM	Local endpoint	Proxy for any model

Self-Hosted Models

json

{
  "providers": {
    "ollama": {
      "type": "openai-compat",
      "base_url": "http://localhost:11434/v1",
      "api_key": "ollama",
      "models": [
        { "id": "llama3.1:8b", "name": "Llama 3.1 8B" },
        { "id": "codellama:7b", "name": "CodeLlama 7B" }
      ]
    }
  }
}

SectionPermissions System — Allow/Ask/Deny

The Permission Triad

Permission Triad + Hooks Pipeline

الحالة	معناها	مثال عملي
ALLOW	ينفذ من غير سؤال	`git status *` — آمن 100%
ASK	يسألك الأول وتختار	`grep *` — ممكن يكون خطر
DENY	ممنوع نهائياً	`rm -rf /` — خطير

Permission Rules (آخر rule بتتنفذ)

json

{
  "permissions": {
    "bash": {
      "rules": [
        { "pattern": "git status *", "decision": "allow" },
        { "pattern": "git diff *", "decision": "allow" },
        { "pattern": "grep *", "decision": "ask" },
        { "pattern": "*", "decision": "deny" }
      ]
    }
  }
}

YOLO Mode

bash

opencode--yolo# كل حاجة تنفذ من غير permission prompt
                # ⚠️ خطر — استخدمه بس لو واثق 100%

SectionHooks System — PreToolUse

Hook Config

json

{
  "hooks": {
    "PreToolUse": [
      {
        "name": "no-rm-rf",
        "matcher": "^bash$",
        "command": "./hooks/no-rm-rf.sh",
        "timeout": 10
      }
    ]
  }
}

الـField	وصفه	إمتى تستخدمه
`name`	اسم descriptive (optional)	عشان تعرف الـhook
`matcher`	regex ضد tool name (optional)	`^bash$` = bash بس، omit = كل الـtools
`command`	الـshell command (required)	المسار بتاع الـscript
`timeout`	بالثواني (default 30)	لو الـhook بيأخذ وقت

Hook في العمل

➜ ~ cat .opencode/pre-tool-use.sh

#!/bin/bash

block rm -rf

echo "$OPENCODE_TOOL_INPUT" | grep -q "rm -rf" && exit 1

exit 0

➜ ~ opencode -p "remove all temp files with rm -rf /"

✗ Hook blocked: dangerous rm command detected

➜ ~⏎ نفّذ · ⌫ امسح

Exit Codes

الـCode	المعنى	بيعمل إيه
`0`	Success — stdout بتـparse كـJSON envelope	ممكن يـallow أو يـdeny أو يـhalt
`2`	Block tool — stderr بيكون الـdeny reason	الـtool call بتتمنع
`49`	Halt turn — الـagent turn بيقف بالكامل	المستخدم ياخد control

JSON Envelope

json

{
  "version": 1,
  "decision": "allow",          // "allow" | "deny" | null
  "halt": false,                // لو true الـturn بيقف
  "reason": "LGTM",            // بيتعرض لما deny/halt
  "context": "Scrubbed secrets", // بيتضاف للـmodel context
  "updated_input": { "command": "…" } // shallow-merge مع tool_input
}

أمثلة عملية

1. امنع rm -rf على الـroot:

bash

#!/usr/bin/env bash
ifecho"$OPENCODE_TOOL_INPUT_COMMAND"|grep-qE'rm\s+-(rf|fr)\s+/';then
echo"Refusing to run rm -rf against root">&2
exit2
fi

2. Auto-approve read-only tools:

json

{ "matcher": "^(view|ls|grep|glob)$", "command": "echo '{\"decision\":\"allow\"}'" }

3. ا inject context لـGo files:

bash

#!/usr/bin/env bash
if[["$OPENCODE_TOOL_INPUT_FILE_PATH"==*.go]];then
echo'{"context": "Run gofumpt after editing."}'
else
echo'{}'
fi

4. اوقف drop database:

bash

#!/usr/bin/env bash
ifecho"$OPENCODE_TOOL_INPUT_COMMAND"|grep-qE'drop\s+database';then
echo"Database drop detected — halting turn">&2
exit49
fi

SectionSkills System — SKILL.md

yaml

name: my-skill
description: What this skill does — critical for LLM tool selection.
user-invocable: true
disable-model-invocation: true
# Skill Instructions
Detailed instructions for the skill...

الـField	القاعدة	ليه
`name`	1–64 chars، lowercase فقط	عشان الـmatching يكون precise
`description`	1–1024 chars	ده اللي الـLLM بيستخدمه يقرر يستدعي الـskill ولا لأ
`user-invocable`	`true` = يظهر في Ctrl+P	عشان المستخدم يقدر يناديه
`disable-model-invocation`	`true` = المستخدم بس اللي يناديه	عشان ميتنفذش لوحدو

Discovery Paths

النوع	الـPath
Global	`~/.config/opencode/skills/`
Global	`~/.agents/skills/`
Global	`~/.claude/skills/`
Project	`.agents/skills/`
Project	`.opencode/skills/`
Custom	`options.skills_paths` في config

SectionContext Files — اللي الـAgent بيقرأها

الـFile	النوع	ملاحظات
`AGENTS.md`	Universal standard	كل الـagents بيفهموه — الـstandard الجديد
`OPENCODE.md`	OpenCode-specific	بيقرأه OpenCode بس
`CLAUDE.md`	Claude Code-specific	بيقرأه Claude Code
`GEMINI.md`	Gemini-specific	بيقرأه Gemini
`.cursorrules`	Cursor-specific	بيقرأه Cursor
`.github/copilot-instructions.md`	Copilot-specific	بيقرأه GitHub Copilot

القاعدة: AGENTS.md هو الـuniversal standard — اكتبه مرة واحدة وكل الـagents هيفهموه.

SectionBuilt-in Tools — المرجع الكامل

File & Code Tools

الـTool	بيعمل إيه	إمتى تستخدمه	ليه مهم
`glob`	بيدور على ملفات بـpattern	لما بتدور على ملفات بنوع معين	أسرع من find
`grep`	بيدور على محتوى ملفات	لما بتدور على string في الكود	بيعمل regex search
`ls`	بيطلع directory tree	لما عايز تشوف الـstructure	بـdepth control
`view`	بيقأ ملف مع line numbers	لما عايز تقرأ ملف	مع `offset` و `limit`
`write`	بيعمل أو بيستبدل ملف	لما بتكتب ملف جديد	بي overwrite كامل
`edit`	find-and-replace في ملف	لما بتعدل جزء من ملف	لازم exact match
`multiedit`	تعديلات كتير في ملف واحد	لما بتعدل أكتر من مكان	sequential edits
`diagnostics`	بيعرض LSP errors/warnings	لما بتدور على bugs في الكود	بيستخدم language server
`references`	بيلاقي symbol references	لما بتدور على إزاي function بيستخدموا	go-to-reference

Execution & Search Tools

الـTool	بيعمل إيه	إمتى تستخدمه	ليه مهم
`bash`	بينفذ shell commands	لما بتشغل tests أو commands	مع timeout و background
`fetch`	بيجيب URL content (raw)	لما بتدور على docs online	مع format: text/markdown/html
`download`	بيـdownload URL لملف	لما بتـdownload binary files	binary-safe streaming
`web_search`	بيعمل web search (DuckDuckGo)	لما بتدور على حاجة على الإنترنت	مع max_results
`web_fetch`	بيجيب URL كـmarkdown (sub-agent)	للـsub-agents	مش للاستخدام المباشر
`sourcegraph`	بيبحث في repos عن كود	لما بتدور على implementation عبر repos	مع count و context_window
`agent`	بيعمل sub-agent	لما الـmain agent محتاج search عميق	limited to glob/grep/ls/view
`agentic_fetch`	web research sub-agent	لما بتدور على معلومات complex	بيتبع links ويعمل iterations

Session & Info Tools

الـTool	بيعمل إيه
`opencode_info`	بيعرض runtime state: model, provider, LSP, MCP, skills, hooks
`opencode_logs`	بيقأ الـinternal logs
`lsp_restart`	بيعمل restart لـLSP client
`job_output`	بيجيب output من background shell
`job_kill`	بيعمل kill لـbackground process
`todos`	بيدير structured task list

SectionKeyboard Shortcuts — اللي لازم تحفظهم

الـShortcut	بيعمل إيه	إمتى تستخدمه
`Ctrl+X` (Leader)	بداية كل shortcuts	ده الـleader key
`Leader n`	New session	لما عايز تبدأ حاجة جديدة
`Leader l`	List sessions	لما عايز ترجع لـsession قديمة
`Ctrl+P`	Command palette	لما عايز تنادي skill أو تعمل حاجة سريعة
`Tab`	Cycle Primary Agents	تبدل بين Build و Plan
`Leader ↓/↑`	Navigate sessions	تتنقل بين parent/child sessions
`Ctrl+G`	Scroll to top	تنزل لفوق في الـchat
`Ctrl+Alt+G`	Scroll to bottom	تنزل لتحت في الـchat
`a`	Allow لـtool call واحد	في الـpermission dialog
`A`	Allow لـكل الـsession	في الـpermission dialog
`d`	Deny	في الـpermission dialog

SectionMCP (Model Context Protocol)

الـType	بيعمل إيه	مثال
`stdio`	بيشتغل كـlocal process	filesystem, databases
`http`	بيتصل بـHTTP endpoint	GitHub, external APIs
`sse`	Server-Sent Events	streaming connections

json

{
  "mcp": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer $GH_PAT" },
      "disabled_tools": ["create_issue"]
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "timeout": 30
    }
  }
}

SectionCrash Recovery — القواعد الأساسية

لما السيرفر يقع → الـagents بتتحول لـ"ready" بس مش بتـrestart
لازم انت تعمل manual restart — عشان مياكلش API credits ليلًا
الـcompaction agent بيعمل auto-summarize على 95% من الـcontext window
الـtitle agent بيعمل أسماء تلقائية لكل session
الـsummary agent بيعمل overviews مستمرة في الـbackground

SectionTUI Themes

الـTheme	الشكل
`opencode`	الـdefault — dark
`catppuccin`	Warm pastel
`dracula`	Purple-dark
`flexoki`	Ink-inspired
`gruvbox`	Retro warm
`monokai`	Classic code editor
`onedark`	Atom-inspired
`tokyonight`	Blue-dark
`tron`	Neon cyan on black

SectionQuick Decision Guide

السيناريو	ابدأ من هنا
أول مرة بتستخدم OpenCode	`opencode` → TUI يفتح
عايز automate حاجة	`opencode -p "..." -f json`
عايز أمنع أوامر خطيرة	أضف hook في `.opencode.json`
عايز auto-approve read-only	`permissions.allowed_tools` أو hook
عايز أدي الـagent قدرات جديدة	اكتب SKILL.md في `.agents/skills/`
عايز الـagent يفهم مشروعك	اكتب `AGENTS.md` في root
عايز تربط MCP tool	أضف في `mcp` في `.opencode.json`
عايز تضيف LSP	أضف في `lsp` في `.opencode.json`
عايز تشتغل على مشروع تاني	`opencode -c /path/to/project`
عايز multi-client	`opencode serve`
عايز تختبر hook	`opencode_logs` أو check exit code

OpenCode — الشيت الكامل: كل الأوامر والإعدادات والتراكيب

OpenCode — Cheatsheet 📋

SectionInstallation & Setup

Install

First Run

SectionCLI Commands

SectionAgent System — الأنواع والأدوار

Primary Agents

Subagents

SectionConfiguration — `.opencode.json`

الـConfig الكامل

Config Paths (بالترتيب)

Provider Environment Variables

Self-Hosted Models

SectionPermissions System — Allow/Ask/Deny

Permission Rules (آخر rule بتتنفذ)

YOLO Mode

SectionHooks System — PreToolUse

Hook Config

Exit Codes

JSON Envelope

أمثلة عملية

SectionSkills System — SKILL.md

Discovery Paths

SectionContext Files — اللي الـAgent بيقرأها

SectionBuilt-in Tools — المرجع الكامل

File & Code Tools

Execution & Search Tools

Session & Info Tools

SectionKeyboard Shortcuts — اللي لازم تحفظهم

SectionMCP (Model Context Protocol)

SectionCrash Recovery — القواعد الأساسية

SectionTUI Themes

SectionQuick Decision Guide

قيّمه عجبك؟ المقال ده

Comments

فهرس المقال

OpenCode — الشيت الكامل: كل الأوامر والإعدادات والتراكيب

OpenCode — Cheatsheet 📋

SectionInstallation & Setup

Install

First Run

SectionCLI Commands

SectionAgent System — الأنواع والأدوار

Primary Agents

Subagents

SectionConfiguration — .opencode.json

الـConfig الكامل

Config Paths (بالترتيب)

Provider Environment Variables

Self-Hosted Models

SectionPermissions System — Allow/Ask/Deny

Permission Rules (آخر rule بتتنفذ)

YOLO Mode

SectionHooks System — PreToolUse

Hook Config

Exit Codes

JSON Envelope

أمثلة عملية

SectionSkills System — SKILL.md

Discovery Paths

SectionContext Files — اللي الـAgent بيقرأها

SectionBuilt-in Tools — المرجع الكامل

File & Code Tools

Execution & Search Tools

Session & Info Tools

SectionKeyboard Shortcuts — اللي لازم تحفظهم

SectionMCP (Model Context Protocol)

SectionCrash Recovery — القواعد الأساسية

SectionTUI Themes

SectionQuick Decision Guide

قيّمه عجبك؟ المقال ده

Comments

فهرس المقال

SectionConfiguration — `.opencode.json`