perplexity-agent-mcp AGENTS.md

Rule: Mandatory Startup Reads

Before taking any action, read @README.md for project context.

Rule: askpplx CLI Usage

Use askpplx for real-time web search via Perplexity. Verify external facts—documentation, API behavior, library versions, best practices—before acting on them. A lookup costs far less than debugging hallucinated code. Run npx -y askpplx --help if unsure of the available options.

Rule: Safe Command Execution

Store commands in arrays, not strings

When Bash expands a string variable, quotes inside become literal characters and whitespace triggers word splitting:

# BAD: quotes are literal, spaces split words
CMD="echo \"hello world\""
$CMD  # outputs: "hello world" (with literal quotes)

# GOOD: array preserves argument boundaries
CMD=(echo "hello world")
"${CMD[@]}"  # outputs: hello world

Never interpolate variables into shell strings

Variables interpolated into shell strings — sh -c, bash -c, eval, ssh host — are reparsed by the shell. Characters like $(...), backticks, or ; in the value execute as code, a classic injection vector:

# BAD: if VAR contains $(malicious), it executes
sh -c "$VAR --write"

# GOOD: direct execution, no shell interpretation
"${CMD[@]}" --write

# GOOD: with xargs, execute the array directly
find . -name '*.js' -print0 | xargs -0 "${CMD[@]}" --write --

When you need shell features (pipes, redirects), use the exec "$@" pattern to pass arguments as positional parameters instead of interpolating them:

# GOOD: arguments passed as $@, not interpolated into the string
xargs -0 sh -c 'exec "$@"' _ "${CMD[@]}" --write --

The _ occupies $0 (the script name), leaving $@ for the command and arguments. Any string works as the placeholder; _ is conventional.

Rule: Avoid Leaky Abstractions

Design interfaces around what callers need, not how the system works internally. An abstraction is leaky when using it correctly requires knowledge of underlying storage, infrastructure, or error behavior. Keep signatures consistent, return domain types instead of backend artifacts, and inject infrastructure dependencies through constructors rather than method parameters.