| name | Pynchy Development |
| description | Use when running pynchy locally — running the app, tests, linting, formatting, prek hooks, or rebuilding the agent container. Also use when determining whether you're on the live Pynchy host or a local machine, and for debugging agent behavior-- session transcript branching, inspecting message history and agent traces in SQLite, pytest hangs, or diagnosing known codebase issues. |
Pynchy Development
Run commands directly—don't tell the user to run them.
Am I on pynchy?
Check hostname and compare it with the deployment-specific live host from local memory, environment, or the operator. If you are on that host, access services at localhost. Otherwise, reach Pynchy over SSH or Tailscale using that configured host.
Commands
uv run pynchy
uv run pytest tests/
uv run ruff check --fix src/
uv run ruff format src/
uvx prek run --all-files
./src/pynchy/agent/build.sh
Isolated feature runtimes
Use new-feature from the control checkout when a feature needs an isolated Pynchy runtime.
See the feature-runtime workflow for create, merge,
restart, and teardown commands. Do not use raw git worktree commands for managed features.
Install or verify its host dependencies with ./scripts/install_new_feature_dependencies.py.
Documentation Lookup
When you need documentation for a library or framework, use the context7 MCP server to get up-to-date docs. Don't rely on training data for API details that may have changed.
Testing Philosophy
Write tests that validate actual business logic, not just line coverage. See references/testing-philosophy.md for what makes a good test vs. coverage theater.
Known Issues
- Transcript branching is closed by construction, not to be reopened casually — native Teams tools (
TeamCreate/TeamDelete/SendMessage) are not allow-listed in either core, so nothing can branch the leader's session transcript. Task sidechains remain allowed (they write off the main chain and resume safely). Reintroducing Teams requires per-teammate session isolation first — tracked in backlog/0-proposed/reintroduce-teams-session-isolation.md.
Debugging Agent Behavior
Prefer querying SQLite over docker logs — docker logs truncate output, but the DB stores full content and captures agent internals (thinking, tool calls, system prompts).
Database: data/messages.db. If not on the Pynchy host, prefix commands with ssh "$PYNCHY_HOST" after setting PYNCHY_HOST to the deployment-specific hostname.
sqlite3 data/messages.db "
SELECT timestamp, sender_name, message_type, substr(content, 1, 120)
FROM messages WHERE chat_jid = '<JID>'
ORDER BY timestamp DESC LIMIT 20;
"
sqlite3 data/messages.db "
SELECT timestamp, chat_jid, json_extract(payload, '$.tool_name') AS tool
FROM events
WHERE event_type = 'agent_trace'
AND json_extract(payload, '$.trace_type') = 'tool_use'
ORDER BY timestamp DESC LIMIT 20;
"
OpenAI Shell Tool Pitfall
If the OpenAI backend shows /bin/sh: Syntax error: word unexpected (expecting ")") for shell tool calls, the shell executor is likely receiving a ShellCommandRequest(...) object and trying to run its repr. Ensure _make_shell_executor in src/pynchy/agent/agent_runner/src/agent_runner/cores/openai.py extracts command from object/mapping shapes (including parsing repr when needed).
If OpenAI tool calls show up with empty tool_input in events, the tool_call_item.raw_item usually carries the data. Common raw_item.type values:
shell_call (uses action.commands), local_shell_call (uses action.command list), apply_patch_call (uses operation), and function_call/mcp_call (uses JSON arguments). Parse those fields before falling back to generic mappings.
