{"id":41230664,"url":"https://github.com/agusmdev/ccv","last_synced_at":"2026-01-23T00:52:15.142Z","repository":{"id":333707080,"uuid":"1138216621","full_name":"agusmdev/ccv","owner":"agusmdev","description":"Claude Code Viewer - A headless Go CLI wrapper for claude that renders structured text output for scripts, automation, and logging","archived":false,"fork":false,"pushed_at":"2026-01-21T00:21:47.000Z","size":343,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-21T01:16:19.295Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agusmdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-20T11:43:39.000Z","updated_at":"2026-01-21T00:21:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agusmdev/ccv","commit_stats":null,"previous_names":["agusmdev/ccv"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/agusmdev/ccv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmdev%2Fccv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmdev%2Fccv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmdev%2Fccv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmdev%2Fccv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agusmdev","download_url":"https://codeload.github.com/agusmdev/ccv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmdev%2Fccv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28676173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T20:48:19.482Z","status":"ssl_error","status_checked_at":"2026-01-22T20:48:14.968Z","response_time":144,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-23T00:52:14.505Z","updated_at":"2026-01-23T00:52:15.130Z","avatar_url":"https://github.com/agusmdev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CCV - Claude Code Viewer\n\n\u003e **Warning**: This project is under active development. APIs and output formats may change between versions. Use with caution in production scripts.\n\nA lightweight headless CLI wrapper for Claude Code that renders structured text output. Perfect for scripts, automation, logging, and headless environments.\n\n\u003cimg width=\"777\" height=\"692\" alt=\"image\" src=\"https://github.com/user-attachments/assets/77d5f72e-d546-4671-af80-dbabc78c885f\" /\u003e\n\n\n## Drop-in Replacement for Headless Scripts\n\n**CCV is designed as a drop-in replacement for `claude` in headless environments.** Simply replace `claude` with `ccv` in your existing scripts to get pretty, structured output instead of raw JSON:\n\n```bash\n# Before (raw stream-json output)\nclaude --print -p \"Explain this code\" --output-format stream-json\n\n# After (pretty formatted output)\nccv \"Explain this code\"\n```\n\nCCV automatically handles all the necessary flags (`--print`, `--output-format stream-json`, `--verbose`) so you can focus on your prompts. All Claude CLI arguments are passed through transparently.\n\n## Features\n\n- **Structured Text Output**: Clean, readable output showing assistant responses, tool calls, and thinking blocks\n- **Real-time Streaming**: Claude's responses stream to stdout as they arrive\n- **Tool Call Formatting**: Tool calls and results are clearly formatted with status indicators\n- **Agent Hierarchy Display**: Shows nested agent context when Task tools spawn sub-agents\n- **Token Usage Tracking**: Displays token counts and cost information\n- **Headless Operation**: No interactive UI - perfect for scripts, CI/CD, and automation\n- **Flexible Output Modes**: Supports verbose, quiet, and JSON output formats\n- **Signal Handling**: Graceful shutdown with proper cleanup on SIGINT/SIGTERM\n\n## Requirements\n\n- Go 1.22 or later (for building from source)\n- [Claude Code CLI](https://docs.anthropic.com/en/docs/quickstart-guide) must be installed and configured\n\n## Installation\n\n### One-Liner Install (Recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/agusmdev/ccv/main/install.sh | bash\n```\n\nThis will automatically:\n- Detect your OS (macOS, Linux) and architecture (amd64, arm64)\n- Download the appropriate binary from GitHub releases\n- Install to `/usr/local/bin` (or `~/.local/bin` if no sudo access)\n- Verify checksums for security\n\n### Using Go Install\n\nIf you have Go installed, you can install directly:\n\n```bash\ngo install github.com/agusmdev/ccv@latest\n```\n\n### Manual Binary Download\n\n1. Visit the [releases page](https://github.com/agusmdev/ccv/releases)\n2. Download the binary for your OS and architecture\n3. Make it executable: `chmod +x ccv`\n4. Move to your PATH: `sudo mv ccv /usr/local/bin/`\n\n### Build from Source\n\n```bash\ngit clone https://github.com/agusmdev/ccv.git\ncd ccv\nmake install\n```\n\nOr manually:\n\n```bash\ngo build -o ccv\nsudo mv ccv /usr/local/bin/\n```\n\n## Usage\n\n### Basic Usage\n\nPass your prompt directly to `ccv`:\n\n```bash\nccv \"Explain this codebase\"\n```\n\n### With Claude Code Arguments\n\nPass Claude Code arguments directly - CCV filters its own flags and passes everything else through:\n\n```bash\nccv -p \"Fix the bug\" --allowedTools Bash,Read\n```\n\n### Output Modes\n\nControl output verbosity with flags:\n\n```bash\n# Default: structured text with moderate detail\nccv \"Explain this codebase\"\n\n# Verbose: include full tool inputs and parameters\nccv --verbose \"Refactor this code\"\n\n# Quiet: only show assistant text responses\nccv --quiet \"What is this project?\"\n\n# JSON: output parsed SDK messages as JSON\nccv --format json \"Analyze the code\"\n\n# Disable colors (useful for logging or piping)\nccv --no-color \"List all files\"\n```\n\n### Piping and Scripting\n\nCCV outputs to stdout, making it perfect for piping:\n\n```bash\n# Save output to a log file\nccv \"Analyze the code\" \u003e analysis.log\n\n# Pipe to other tools\nccv \"List all functions\" | grep \"export\"\n\n# Use in scripts\nOUTPUT=$(ccv --quiet \"What is the main entry point?\")\necho \"Entry point: $OUTPUT\"\n```\n\n### Examples\n\nAnalyze a codebase:\n```bash\nccv \"Analyze the architecture of this project\"\n```\n\nDebug with specific tools:\n```bash\nccv -p \"Debug the authentication flow\" --allowedTools Read,Grep\n```\n\nGet help:\n```bash\nccv --help\n```\n\nCheck version:\n```bash\nccv --version\n```\n\n## Configuration\n\n### CCV Flags\n\n| Flag | Description |\n|------|-------------|\n| `--verbose` | Show verbose output including full tool inputs |\n| `--quiet` | Show only assistant text responses |\n| `--format \u003cfmt\u003e` | Output format: `text` (default) or `json` |\n| `--no-color` | Disable colored output |\n| `--help` | Show help information |\n| `--version` | Show version information |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `CCV_VERBOSE=1` | Equivalent to `--verbose` |\n| `CCV_QUIET=1` | Equivalent to `--quiet` |\n| `CCV_FORMAT=json` | Equivalent to `--format json` |\n| `NO_COLOR=1` | Disable colored output (standard [no-color.org](https://no-color.org/)) |\n| `TERM=dumb` | Also disables colored output |\n\n### Claude Code Configuration\n\nCCV respects your existing Claude Code configuration. Make sure Claude Code is properly configured:\n\n```bash\nclaude auth login\n```\n\nFor more Claude Code configuration options, see the [official documentation](https://docs.anthropic.com/en/docs/quickstart-guide).\n\n## How It Works\n\nCCV wraps the Claude Code CLI and:\n1. Spawns Claude Code as a subprocess with `--output-format stream-json`\n2. Parses the streaming NDJSON output from Claude Code's SDK\n3. Formats and outputs structured text to stdout in real-time\n4. Handles signals and cleanup for graceful shutdown\n\nThe output includes:\n- **Assistant Messages**: Claude's text responses streamed as they arrive\n- **Tool Calls**: Function calls with name, description, and status\n- **Tool Results**: Results from executed tools (indented under tool calls)\n- **Thinking Blocks**: Claude's reasoning process with `[THINKING]` prefix\n- **Agent Context**: Shows current agent type and status (e.g., `[main: running]`)\n- **Token Usage**: Token counts and cost summary at completion\n\n## Development\n\n### Project Structure\n\n```\nccv/\n├── main.go      # Entry point and flag handling\n├── runner.go    # Claude Code subprocess management\n├── output.go    # Text output processor and message formatting\n├── types.go     # Message and event type definitions\n├── colors.go    # Terminal color scheme and ANSI codes\n├── format.go    # Text formatting utilities\n└── go.mod       # Go module dependencies\n```\n\n### Running Locally\n\n```bash\ngo run . \"Your prompt here\"\n```\n\n### Building\n\n```bash\ngo build -o ccv\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Wraps [Claude Code](https://docs.anthropic.com/en/docs/quickstart-guide) - Anthropic's official CLI for Claude\n- Built with Go's standard library for robust subprocess management and concurrent processing\n\n## Support\n\nIf you encounter any issues or have questions:\n- Open an issue on [GitHub](https://github.com/agusmdev/ccv/issues)\n- Check the [Claude Code documentation](https://docs.anthropic.com/en/docs/quickstart-guide)\n- Make sure Claude Code CLI is properly installed and configured\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagusmdev%2Fccv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagusmdev%2Fccv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagusmdev%2Fccv/lists"}