Strands Code

A Claude Code / Codex-class coding CLI built on the Strands harness. Forked from aws-samples/sample-strands-code-agent; its agent library is preserved underneath, and a deny-first CLI is layered on top: session-sticky Plan/Act, gated tools, skills, repo memory, and a /btw side channel.

Experimental: tracks fast-moving upstream (strands-agents, strands-harness). Expect churn; wrappers stay thin on purpose.

Design directives

1. Harness-first, gaps-only. Adopt strands-harness (create_harness()) for tools, sessions, skills, memory, context management, and effort presets. Build only genuine CLI gaps: slash commands, permissions UX, file picker, memory-tier backends.
2. Deny-first tool-calling. Gated file/shell tools are the default action interface: every side effect passes a deny-first approval prompt that fails closed on ambiguity. Code-generation-first (CodeAct) arrives later as an opt-in interface (Phase 9) — never mandatory, never the default.
3. AWS-optional, never AWS-required. Bedrock (LLM, KB memory, embeddings) and AgentCore are first-class choices behind config flags. Defaults are local: file sessions, markdown memory, sandboxed interpreter. The agentcore extra stays optional.
4. Tiered memory. Local markdown files by default (offline, private) → Hindsight opt-in (team, temporal reasoning) → memsearch/Milvus (enterprise scale). All behind one memory seam.
5. Loose dependencies, thin wrappers. No upper pins during the experimental phase; upstream syncs via the upstream remote.

Details: docs/competitive-gap-analysis.md.

Quick start

uv sync                   # project-local .venv + lockfile, incl. strands-harness

Full run guide: docs/QUICKSTART.md.

Run the CLI

From this repo:

uv run strands-code

From any other directory (sessions stay local to that directory):

uv run --project <path-to-repo> strands-code

Sessions live in ./.agent/sessions relative to your working directory — cd into the repo you want to work on, then launch. Resume with strands-code --session-id <uuid> or the picker at launch.

First run without AWS credentials stops with a Bedrock setup pointer (exit 2); the provider choice persists to a config file afterwards.

REPL basics: type an ask, keep asking — one conversation. /resume, /rename, /forget, /model, /cost [refresh|table], /compact, /clear, /context, /mode, /approve, /diff, /search, /policy, /skills, /init, /memory, /btw, /exit work; unknown /slash shows a usage hint. Ask a side question mid-task with /btw — the main task keeps running. Ctrl-C cancels a running task (asks which when main + side both run), Ctrl-D exits with state saved. See docs/QUICKSTART.md for the live-pricing sources behind /cost.

Library use

from strands_code_agent import CodeAgent

agent = CodeAgent()
response = agent("What is 2 ** 10?")

The agent receives a python_repl tool automatically and solves tasks by writing and executing Python code.

Library essentials

Piece	What it is
CodeAgent	strands.Agent subclass; auto-registers python_repl, assembles the system prompt from toolkits (strands_code_agent/code_agent.py). Extra tools via tools=[...]; model etc. via **kwargs.
Toolkit	Domain bundle: libraries → interpreter allowlist, initialization_code → REPL preamble, usage_instructions → prompt guidance, domain_specific_code → auto-imported + documented symbols. Ships VISUALIZATION_TOOLKIT, DATA_ANALYSIS_TOOLKIT.
Interpreters	SandboxedPythonInterpreter (default, allowlisted), ExecPythonInterpreter (trusted, unrestricted), AgentCorePythonInterpreter (remote Bedrock AgentCore sandbox; needs uv sync --extra agentcore + AWS creds). Selected via python_interpreter_class.
Knowledge (OKF)	strands_code_agent.knowledge: convert PDFs to OKF concept bundles, navigate via find / read / children / toc. See examples/pdf_to_okf_bundle/.
Callback	CodeAgentCallbackHandler: Rich terminal rendering (code highlighting, Markdown/JSON detection).

from strands_code_agent import CodeAgent, Toolkit
from strands_code_agent.toolkits import DATA_ANALYSIS_TOOLKIT, VISUALIZATION_TOOLKIT

agent = CodeAgent(
    system_prompt="You are a data analyst.",
    toolkits=[DATA_ANALYSIS_TOOLKIT, VISUALIZATION_TOOLKIT],
)

CLI status

Working today (Phase 7 complete): resumable multi-ask REPL, resume picker with session deletion, --session-id, /resume /rename /forget /exit, /model switching with history conversion, /cost /context display, /compact /clear, Plan/Act modes (/mode, /approve), anytime steering, gated /diff review, /search, /policy with standing rules, local skills (/skills), repo memory (/init, /memory), session auto-titles, Bedrock-or-stop first-run gate, kill-safe persistence, and the /btw side channel (parallel side questions under the same deny-first gate). Coming next: decision-model routing (Phase 8), opt-in CodeAct (Phase 9), /review, fuzzy file picker.

Upstream sync

git fetch upstream   # aws-samples/sample-strands-code-agent
git merge upstream/main

Tests

uv run pytest tests/ -v

Live AgentCore tests need uv sync --extra agentcore, AWS credentials, and AWS_REGION.

License

MIT-0. See LICENSE.